Add mkdocs configuration for the release docs (#326)

gotmax23 · oraNod · web-flow · commit 49f44ae98b9b · 2023-12-04T14:58:12.000Z
Co-authored-by: Don Naro &lt;dnaro@redhat.com&gt;
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,10 @@
+---
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - pip install -U nox
+    - mkdir -p _readthedocs/html/
+    - nox -e mkdocs -- build --site-dir=_readthedocs/html
diff --git a/docs-requirements.txt b/docs-requirements.txt
@@ -0,0 +1,2 @@
+mkdocs
+mkdocs-ansible
diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md
@@ -4,6 +4,9 @@
 - The docs in this directory should follow the [Semantic Line Breaks][1] standard.
 - The docs in this directory should follow the [Ansible documentation style guide][2]
   when applicable.
+- The docs in this directory should use `Title Case` for page headings and
+  `Sentence case` for subheadings.
+- Make sure to add new docs to the `nav:` config in `mkdocs.yml`.
 
 [1]: https://sembr.org/
 [2]: https://docs.ansible.com/ansible/latest/dev_guide/style_guide/basic_rules.html
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1 @@
+../README.md
diff --git a/docs/policies.md b/docs/policies.md
@@ -69,40 +69,43 @@ In case of violations, the release manager must preform the following steps:
 1. First, the collection must be restricted to the previous tagged release in
    the `ansible-VERSION.constraints` file.
 
-   Take the `community.docker` collection as an example. If its version 3.9.0
-   was released and correctly tagged, and 3.9.1 was released but not correctly
-   tagged, add
+    Take the `community.docker` collection as an example. If its version 3.9.0
+    was released and correctly tagged, and 3.9.1 was released but not correctly
+    tagged, add
 
-   ```
-   community.docker: <3.9.1
-   ```
+    ```
+    community.docker: <3.9.1
+    ```
 
 2. Commit only the changed `ansible-VERSION.constraints` file:
 
     ```
     git add 8/ansible-8.constraints
     git commit -m "pin community.docker to previous release"
     ```
+
 3. Rerun the release playbook.
    In this example, the ansible distribution will be built with
    community.docker 3.9.0 even though community.docker 3.9.1 is the latest
    version.
+
 4. Proceed with the rest of the release process as normal.
    Commit the other changed files.
    The collection release PR should be applied using the `Rebase and merge`
    option (as opposed to `Squash and merge`) so the first commit can be more
    easily reverted when/if the collection fixes the issue.
+
 5. The release manager or another community member needs to file an issue in
    the violating collection's issue tracker.
    This part should not block the current ansible package release,
    but the issue must have been filed before the following minor release.
    The following issue template can be used:
 
-   ``` markdown
-   Hi! As part of the ansible community package release process, we've determined that version {VERSION} of {COLLECTION} was released to Ansible Galaxy but not properly tagged in this Git repository.
-   This violates the [repository management][1] section of the Collection Requirements:
+    ``` markdown
+    Hi! As part of the ansible community package release process, we've determined that version {VERSION} of {COLLECTION} was released to Ansible Galaxy but not properly tagged in this Git repository.
+    This violates the [repository management][1] section of the Collection Requirements:
 
-   [1]: https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_requirements.html#repository-management
+    [1]: https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_requirements.html#repository-management
 
     > Every collection MUST have a public git repository. Releases of the collection MUST be tagged in said repository. This means that releases MUST be `git tag`ed and that the tag name MUST exactly match the Galaxy version number. Tag names MAY have a `v` prefix, but a collection's tag names MUST have a consistent format from release to release.
     >
@@ -112,7 +115,8 @@ In case of violations, the release manager must preform the following steps:
 
     [2]: https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#collections-not-satisfying-the-collection-requirements
 
-   ```
+    ```
+
 6. Post a comment in <https://github.com/ansible-community/ansible-build-data/issues/223>
    with a link to the issue.
 
diff --git a/docs/release-process.md b/docs/release-process.md
@@ -4,10 +4,9 @@
 
 This document describes the ansible community package release process.
 
-> **Note**
->
-> Throughout this page, placeholder values in code blocks are formatted as
-> `${PLACEHOLDER_VALUE}` where `PLACEHOLDER_VALUE` describes the value to fill in.
+!!! note
+    Throughout this page, placeholder values in code blocks are formatted as
+    `${PLACEHOLDER_VALUE}` where `PLACEHOLDER_VALUE` describes the value to fill in.
 
 
 ## Set up container
@@ -29,32 +28,34 @@ First, you need to set up ansible-build-data and antsibull repository clones.
 This only needs to be done once.
 
 1. [Fork][abd-fork] the [ansible-build-data] repository.
+
 2. Checkout the antsibull and ansible-documentation repositories
    and change into antsibull.
 
-   ```
-   git clone https://github.com/ansible/ansible-documentation
-   git clone https://github.com/ansible-community/antsibull
-   cd antsibull
-   ```
+    ```
+    git clone https://github.com/ansible/ansible-documentation
+    git clone https://github.com/ansible-community/antsibull
+    cd antsibull
+    ```
+
 3. Checkout ansible-build-data and configure your fork.
 
-   To checkout the repository run
+    To checkout the repository run
 
-   ```
-   mkdir build
-   cd build
-   git clone https://github.com/ansible-community/ansible-build-data
-   cd ansible-build-data
-   ```
+    ```
+    mkdir build
+    cd build
+    git clone https://github.com/ansible-community/ansible-build-data
+    cd ansible-build-data
+    ```
 
-   Then, configure your fork.
-   This guide uses your Github username as the fork remote name.
+    Then, configure your fork.
+    This guide uses your Github username as the fork remote name.
 
-   ```
-   git remote add ${USERNAME} https://github.com/${USERNAME}/ansible-build-data
-   git fetch ${USERNAME} -v
-   ```
+    ```
+    git remote add ${USERNAME} https://github.com/${USERNAME}/ansible-build-data
+    git fetch ${USERNAME} -v
+    ```
 
 ## Perform release process
 
@@ -64,82 +65,81 @@ This only needs to be done once.
 
 2. Create a clean virtual environment for the release process.
 
-   ```
-   rm -rf release-venv
-   python3 -m venv release-venv
-   . ./release-venv/bin/activate
-   python3 -m pip install -U pip
-   ```
+    ```
+    rm -rf release-venv
+    python3 -m venv release-venv
+    . ./release-venv/bin/activate
+    python3 -m pip install -U pip
+    ```
 
-   Install the `antsibull`, `ansible-core`, and `twine` python packages,
-   as well as the community.general collection.
+    Install the `antsibull`, `ansible-core`, and `twine` python packages,
+    as well as the community.general collection.
 
-   ```
-   python3 -m pip install antsibull ansible-core twine
-   ansible-galaxy collection install --force community.general
-   ```
+    ```
+    python3 -m pip install antsibull ansible-core twine
+    ansible-galaxy collection install --force community.general
+    ```
 
 3. Run the [ansible release playbook][release-playbook]
    with the appropriate options.
    You can see the [argument spec][release-playbook-args]
    for a full breakdown, but this describes the basic usage.
 
-   ```
-   export ANSIBLE_CALLBACK_RESULT_FORMAT=yaml
-   ansible-playbook playbooks/build-single-release.yaml -e antsibull_ansible_version=${VERSION}
-   ```
+    ```
+    export ANSIBLE_CALLBACK_RESULT_FORMAT=yaml
+    ansible-playbook playbooks/build-single-release.yaml -e antsibull_ansible_version=${VERSION}
+    ```
 
-   > **Note**
-   >
-   > When building ansible versions greater than 9.0.0a1,
-   > `Validate tags file` task failures will fail the release playbook instead
-   > of warning and moving on.
-   > See [policies.md][tagging-enforcement] for how to proceed if this step fails.
+    !!! note
+        When building ansible versions greater than 9.0.0a1,
+        `Validate tags file` task failures will fail the release playbook instead
+        of warning and moving on.
+        See [policies.md][tagging-enforcement] for how to proceed if this step fails.
 
 4. Commit the changes and push them to your fork.
 
-   You can run the following commands to do so
+    You can run the following commands to do so
 
-   ```
-   cd build/ansible-build-data
-   git switch -c release-${VERSION}
-   git add ${MAJOR_VERSION}/
-   git commit -m "Ansible ${VERSION}: Dependencies, changelog and porting guide"
-   git push -u ${USERNAME} release-${VERSION}
-   ```
+    ```
+    cd build/ansible-build-data
+    git switch -c release-${VERSION}
+    git add ${MAJOR_VERSION}/
+    git commit -m "Ansible ${VERSION}: Dependencies, changelog and porting guide"
+    git push -u ${USERNAME} release-${VERSION}
+    ```
 
-   Then, submit a pull request against ansible-build-data upstream.
+    Then, submit a pull request against ansible-build-data upstream.
 
 5. Submit a PR to ansible/ansible-documentation to add the new porting guide to the docsite.
    Copy the porting guide to the ansible docsite directory
    in your ansible checkout with the following command
 
-   ```
-   cp ${MAJOR_VERSION}/porting_guide_${MAJOR_VERSION}.rst ../ansible-documentation/docs/docsite/rst/porting_guides/
-   ```
+    ```
+    cp ${MAJOR_VERSION}/porting_guide_${MAJOR_VERSION}.rst ../ansible-documentation/docs/docsite/rst/porting_guides/
+    ```
 
-   switch to the ansible checkout,
-   commit and push the changes,
-   and then submit a PR as you normally would.
-   You can use `Add Ansible community ${VERSION} porting guide` as the commit message.
+    switch to the ansible checkout,
+    commit and push the changes,
+    and then submit a PR as you normally would.
+    You can use `Add Ansible community ${VERSION} porting guide` as the commit message.
 
 6. Once the ansible-build-data PR has been merged,
    publish the build artifacts to PyPI.
    From the antsibull repository root, run
 
-   ```
-   twine upload build/ansible-${VERSION}.tar.gz build/ansible-${VERSION}*.whl
-   ```
+    ```
+    twine upload build/ansible-${VERSION}.tar.gz build/ansible-${VERSION}*.whl
+    ```
 
 7. Tag the release commit in the ansible-build-data repository.
 
-   ```
-   cd build/ansible-build-data
-   git switch main
-   git pull
-   git tag ${VERSION} ${MERGED_PR_COMMIT_HASH} -a -m "Ansible ${VERSION}: Changelog, Porting Guide and Dependent Collection Details"
-   git push --follow-tags
-   ```
+    ```
+    cd build/ansible-build-data
+    git switch main
+    git pull
+    git tag ${VERSION} ${MERGED_PR_COMMIT_HASH} -a -m "Ansible ${VERSION}: Changelog, Porting Guide and Dependent Collection Details"
+    git push --follow-tags
+    ```
 
 8. Announce the release on Matrix and the mailing list.
    TODO: Move announcement templates into this repository.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,31 @@
+---
+site_name: Ansible Package Release Management
+site_url: https://ansible.readthedocs.io/projects/ansible-build-data
+repo_url: https://github.com/ansible-community/ansible-build-data
+theme:
+  name: ansible
+  features:
+    - content.code.copy
+    - navigation.footer
+  # NOTE(gotmax23): I dislike web fonts in general and the Red Hat fonts from
+  # the Ansible theme in particular
+  font: false
+# REUSE-IgnoreStart
+copyright: >
+  Copyright (C) 2023 Ansible Project Authors |
+  SPDX-License-Identifier: <a style="text-decoration: underline;" href="https://github.com/ansible/ansible/blob/devel/COPYING">GPL-3.0-only</a>
+# REUSE-IgnoreEnd
+markdown_extensions:
+  # Builtin
+  - admonition
+  - toc:
+      permalink: true
+  # pymdownx
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+nav:
+  - Ansible Build Data: README.md
+  - release-process.md
+  - policies.md
+  - new-ansible-and-freezes.md
diff --git a/noxfile.py b/noxfile.py
@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import nox
+
+
+@nox.session
+def mkdocs(session: nox.Session):
+    session.install("-r", "docs-requirements.txt")
+    session.run("mkdocs", *(session.posargs or ["build"]))
