Revise readthedocs content

[iamianmullins]

readthedocs isn't structured sensibly at present.
Minimizing RTD content to serve as an appropriate starting point to improve structure.

Summary by Sourcery

Restructure and improve documentation for the QM project, creating a more organized and informative documentation structure on Read the Docs.

Enhancements:

• Refactor README.md to improve language and clarity of contribution guidance
• Update internal documentation links to use more consistent and correct paths

Documentation:

• Revise the documentation structure by adding new markdown files for index, getting started, and additional resources
• Update mkdocs configuration to reflect new documentation layout
• Improve documentation content with clearer project description and installation instructions

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request restructures the documentation for the QM project, moving the documentation files to a new 'docs/docs' directory. It also adds a new index page, a getting started guide, and a page with additional resources. Furthermore, it updates documentation links and paths across project files to reflect the new documentation structure.

No diagrams generated as the changes look simple and do not need a visual representation.

File-Level Changes

Change	Details	Files
Restructured the documentation layout and navigation in mkdocs.yml.	Updated the repo_url and repo_name to reflect the correct repository. Added an edit_uri to enable direct editing of documentation files. Organized the navigation menu to include 'Getting Started' and 'Additional resources' sections. Configured the pymdownx.snippets extension to use the 'docs' directory as the base path.	docs/mkdocs.yml
Updated the README to align with the new documentation structure.	Corrected a typo and rephrased a sentence in the Development section to improve clarity. Updated the link to the development README guide to reflect the new documentation location.	README.md
Updated a documentation link in SUBPACKAGES.md.	Modified the link to the 'Creating your own drop-in QM sub-package' guide to match the updated documentation structure.	docs/devel/experimental/SUBPACKAGES.md
Added a new index page to the documentation.	Introduced a comprehensive overview of the QM project, detailing its purpose and functionality. Explained the containerized environment and its role in preventing interference with other system processes. Described the usage of systemd, Podman, and quadlet for isolating applications and containers. Clarified the process of isolating software installed under /usr/lib/qm/rootfs.	docs/docs/index.md
Created a getting started guide for QM installation.	Provided instructions for installing QM on Fedora and CentOS-Stream systems. Included a direct installation command using dnf. Added a link to CentOS Automotive SIG mirrors for specific QM versions.	docs/docs/getting_started/installation.md
Added a page with additional resources related to QM.	Included links to relevant videos and resources, such as DevConf talks and security analysis examples.	docs/docs/resources.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!
• Generate a plan of action for an issue: Comment @sourcery-ai plan on
  an issue to generate a plan of action for it.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @iamianmullins - I've reviewed your changes - here's some feedback:

Overall Comments:

• Consider adding a brief explanation of why the readthedocs structure wasn't sensible and what problems this change addresses.
• It looks like you're moving the development README - make sure that link isn't broken.

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Yarboa]

Consider running automation with github actions

[iamianmullins]

Consider running automation with github actions

@pypingou , I wonder could you help out with this. I've added this github workflow for ReadTheDocs. it's failing here, but I can see RTD successfully generated the preview. I suspect it's something to do with the webhook permissions to write to a pull request, but I don't have access to check.

[pypingou]

Consider running automation with github actions

@pypingou , I wonder could you help out with this. I've added this github workflow for ReadTheDocs. it's failing here, but I can see RTD successfully generated the preview. I suspect it's something to do with the webhook permissions to write to a pull request, but I don't have access to check.

Is this a chicken-egg problem where the pipeline can't run until it's merged? From an ACL POV it looks good to me, the token has the "Pull Request" checkbox which includes: Pull request assigned, auto merge disabled, auto merge enabled, closed, converted to draft, demilestoned, dequeued, edited, enqueued, labeled, locked, milestoned, opened, ready for review, reopened, review request removed, review requested, synchronized, unassigned, unlabeled, or unlocked.

[sourcery-ai]

Hey @iamianmullins - I've reviewed your changes - here's some feedback:

Overall Comments:

• Consider adding a brief explanation of the rationale behind the documentation changes in the PR description.
• The addition of the RTD workflow is great, but consider testing it to ensure it functions as expected.

Here's what I looked at during the review

• 🟡 General issues: 2 issues found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[iamianmullins]

@Yarboa , the github action is failing due to permissions. Removing this piece for now until we can figure that out. I've opened a separate issue to track this.

[Yarboa]

This should have per PR automates test into github actions, isnt it?

.github/workflows/mkdocs-check.yml

name: MkDocs Build Check

on:
  pull_request:
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '**.md'

jobs:
  mkdocs-build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install MkDocs and dependencies
        run: |
          pip install \
            mkdocs \
            mkdocs-material \
            pymdown-extensions

      - name: Build MkDocs site
        run: mkdocs build --strict

Consider running this

[sourcery-ai]

Hey @iamianmullins - I've reviewed your changes - here's some feedback:

Overall Comments:

• Consider using a tool like mkdocs-redirects to handle old links and prevent broken URLs.
• Double-check the edit_uri in mkdocs.yml to ensure it points to the correct location for editing the documentation files.

Here's what I looked at during the review

• 🟡 General issues: 3 issues found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Yarboa]

@Yarboa , the github action is failing due to permissions. Removing this piece for now until we can figure that out. I've opened a separate issue to track this.

Please refer my suggestion per PR

[dougsland]

@iamianmullins please lets us know when the PR is ready for review/merge.

[iamianmullins]

Thanks for the suggestions @Yarboa , much appreciated. @dougsland this should be good for review now, thanks!

[dougsland]

LGTM