Refactor docs building and make changelog visible in web interface (#314

)
ansible · Sep 9, 2024 · 5659368 · 5659368
1 parent cd26afe
commit 5659368
Show file tree

Hide file tree

Showing 14 changed files with 37 additions and 18 deletions.
diff --git a/.config/README.md b/.config/README.md
@@ -4,3 +4,8 @@ process has not missed any files or included any extra files.
 
 If you add new files, you might need to also update this file or the CI/CD
 pipeline will complain about it being out-of sync.
+
+# Requirements
+
+All `requirements*.in` files need this names in order to allow dependabot
+to [function correctly](https://github.com/dependabot/dependabot-core/issues/10007).
diff --git a/.config/dictionary.txt b/.config/dictionary.txt
@@ -33,6 +33,7 @@ containerd
 darglint
 deadsnakes
 digestmod
+docsite
 dynatrace
 envlist
 extfile

diff --git a/.config/manifest.txt b/.config/manifest.txt
@@ -2,16 +2,10 @@
 .flake8
 .gitignore
 bindep.txt
-CHANGELOG.md
 CONTRIBUTING.md
 docs/
-docs/.changelog.yml
-docs/.gitignore
-docs/antsibull-docs.cfg
-docs/build.sh
-docs/conf.py
-docs/docsite/
-docs/docsite/links.yml
+docs/CHANGELOG.md
+docs/README.md
 extensions/
 extensions/eda/
 extensions/eda/plugins/
@@ -111,4 +105,3 @@ schemas/README.md
 tests/
 tests/integration/
 tests/__init__.py
-test_requirements.txt
diff --git a/.config/requirements-docs.txt → .config/requirements-docs.in b/.config/requirements-docs.txt → .config/requirements-docs.in
diff --git a/test_requirements.txt → .config/requirements-test.in b/test_requirements.txt → .config/requirements-test.in
@@ -1,4 +1,4 @@
--r requirements.txt
+-r requirements.in
 coverage-enable-subprocess>=1.0 # see https://github.com/nedbat/coveragepy/issues/1341#issuecomment-1228942657
 coverage==6.5.0; python_version < "3.10"  # ansible-core will complain
 coverage[toml] == 7.3.2; python_version >= "3.10" # ansible-core will complain

diff --git a/.config/requirements-test.txt b/.config/requirements-test.txt
diff --git a/.config/requirements.txt → .config/requirements.in b/.config/requirements.txt → .config/requirements.in
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -17,6 +17,11 @@ updates:
           # galaxy-importer ceiling confuses dependabot
           - attrs
           - bleach
+          - flake8
+    exclude:
+      - dependency-name: attrs
+      - dependency-name: bleach
+      - dependency-name: flake8
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

diff --git a/.gitignore b/.gitignore
@@ -37,3 +37,4 @@ tests/integration/inventory
 importer_result.json
 docs/rst/CHANGELOG.md
 CHANGELOG.md
+docs/README.md
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -16,6 +16,7 @@ build:
     - asdf plugin add github-cli
     - asdf install
     - git fetch --unshallow || true
+    - git fetch --tags
     - pip install --user tox
     - python3 -m tox -e docs
     - mkdir -p $READTHEDOCS_OUTPUT

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -70,7 +70,7 @@ We recommend setting up a Python virtual environment to install the test depende
 
 3. Install the test requirements:
 
-        pip install -r test_requirements.txt
+        pip install -r .config/requirements.in
 
 ## Sanity and Unit tests
 

diff --git a/docs/build.sh b/docs/build.sh
@@ -7,6 +7,9 @@ trap "{ popd; }" EXIT
 GALAXY_VERSION=$(python -c "import yaml; print(yaml.safe_load(open('../galaxy.yml'))['version'])")
 # Determine the collection version, if current commit is tagged, use it. Otherwise, generate pre-release version.
 
+# this is for inclusion in collection archive (galaxy renders docs/*.md in the web UI)
+cp -f ../README.md ./README.md
+
 # Create collection documentation
 mkdir -p rst
 chmod og-w rst  # antsibull-docs wants that directory only readable by itself
@@ -20,10 +23,14 @@ antsibull-docs \
     --dest-dir rst \
     ansible.eda
 
+
 # To be included inside the built collection archive
 pushd ..
 mk -v changelog
-cp CHANGELOG.md ./docs/rst/changelog.md
+cp -f CHANGELOG.md ./docs/CHANGELOG.md
+
+# that is for our sphinx build site:
+cp -f CHANGELOG.md ./docs/rst/changelog.md
 popd
 
 CHANGELOG_VERSION=$(grep -m 1 '^#' rst/changelog.md  | awk '/^#/ {print $2; exit}' | sed 's/v//')

diff --git a/galaxy.yml b/galaxy.yml
@@ -77,13 +77,20 @@ build_ignore:
   - .tool-versions
   - .tox
   - .venv
+  - CHANGELOG.md
   - ansible_collections
   - changelogs/.plugin-cache.yaml
   - codecov.yml
   - collections
   - cspell.config.yaml
   - demos
+  - docs/.changelog.yml
+  - docs/.gitignore
+  - docs/antsibull-docs.cfg
   - docs/build
+  - docs/build.sh
+  - docs/conf.py
+  - docs/docsite
   - docs/rst
   - docs/temp-rst
   - pyproject.toml

diff --git a/tox.ini b/tox.ini
@@ -26,7 +26,7 @@ ignore_basepython_conflict = false
 description =
   Run unit tests
   py{39,310,311,312,313}: with {basepython}
-deps = -r test_requirements.txt
+deps = -r .config/requirements-test.in
 commands_pre =
   bash -c 'test "$(basename $(cd ../.. && pwd))" == ansible_collections || { echo "Repository must be cloned inside a directory structure like ansible_collections/ansible/eda in order allow ansible-test to run."; exit 3;}'
 commands =
@@ -106,7 +106,7 @@ commands =
    pre-commit run --hook-stage=manual deps
 
 [testenv:integration,py{39,310,311,312,313}-integration]
-deps = -r test_requirements.txt
+deps = -r .config/requirements-test.in
 description =
   Run integration tests
   py{39,310,311,312,313}: with {basepython}
@@ -152,7 +152,7 @@ deps =
   py{310,311,312}-sanity-ansible2.16: ansible-core>=2.16,<2.17
   py{310,311,312}-sanity-ansible2.17: ansible-core>=2.17,<2.18
   py{310,311,312}-sanity-ansible2.18: ansible-core>=2.18,<2.19
-  -r test_requirements.txt
+  -r .config/requirements-test.in
 description =
   Run ansible-test sanity (via docker)
   py{39,310,311,312,313}: with {basepython}
@@ -163,7 +163,7 @@ commands =
 
 [testenv:coverage]
 description = Produce final coverage report for GHA
-deps = -r test_requirements.txt
+deps = -r .config/requirements-test.in
 commands =
   ansible-test coverage report --requirements --omit '.tox/*,tests/*' --color --all --show-missing -v --truncate 0
   # produces: tests/output/coverage/coverage.combined
@@ -177,7 +177,7 @@ description = Generate plugins documentation under /docs directory using antsibu
 env_dir = {env:READTHEDOCS_VIRTUALENV_PATH:{work_dir}/docs}}
 deps =
   ansible-core
-  -r .config/requirements-docs.txt
+  -r .config/requirements-docs.in
 commands_pre =
   # --force must remain here or we risk on building docs for older version
   ansible-galaxy collection install --force .