Use antsibull 0.40.1 for docsite build #76675

felixfontein · 2022-01-07T12:22:42Z

SUMMARY

Use the latest release of antsibull to build the docsite. It uses RST tables instead of HTML blobs for option and return value tables, and these tables are responsive.

ISSUE TYPE

Docs Pull Request

COMPONENT NAME

docsite

felixfontein · 2022-01-07T23:01:43Z

0.40.0 crashed during the test docsite build; 0.40.1 fixes the crash (antsibull now has tests to prevent this kind of crash).

ansibot · 2022-01-07T23:04:21Z

The test ansible-test sanity --test docs-build [explain] failed with the error:

Command "/root/.ansible/test/venv/sanity.docs-build/3.10/3cd8b961/bin/python /root/ansible/test/sanity/code-smell/docs-build.py" returned exit status 1.
>>> Standard Error
Command 'make core_singlehtmldocs' failed with status code: 2
--> Standard Output
Creating symlinks in core_structure
ln -sf ../rst/core_index.rst rst/index.rst
ln -sf ../sphinx_conf/core_conf.py rst/conf.py
../../hacking/build-ansible.py collection-meta --template-file=../templates/collections_galaxy_meta.rst.j2 --output-dir=rst/dev_guide/  ../../lib/ansible/galaxy/data/collections_galaxy_meta.yml
../../hacking/build-ansible.py document-config --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/  ../../lib/ansible/config/base.yml
mkdir -p rst/cli
../../hacking/build-ansible.py generate-man --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst  ../../lib/ansible/cli/*.py
../../hacking/build-ansible.py document-keywords --template-dir=../templates --output-dir=rst/reference_appendices/ ../../lib/ansible/keyword_desc.yml 
../../hacking/build-ansible.py docs-build base -o rst
--> Standard Error
usage: antsibull-docs [-h] [--version] [--config-file CONFIG_FILE]
                      {devel,stable,current,collection,plugin,sphinx-init} ...
antsibull-docs: error: unrecognized arguments: --ansible-core-source /root/ansible
make: *** [Makefile:205: base_plugins] Error 2

click here for bot help

samccann

verified on jenkins and local build that this works.
fwiw I changed max_threads to 1 on my vm to get the build to work w/o timeouts.

samccann

Forgot one more place this needs to change I think. We need to keep the docs_build requirements file in sync with this.
https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/docs-build.requirements.txt#L7

samccann · 2022-01-10T18:32:56Z

Hmm top of that file (docs-build.requirements.txt sez to generate it w/ another file so might need edits somewhere else? or maybe just regenerate the file??

felixfontein · 2022-01-10T18:37:37Z

@samccann I think changing that file prevents this from being backported to any stable branch.

felixfontein · 2022-01-10T18:39:26Z

On the other hand, the code-smell test is internal to ansible/ansible, so maybe this doesn't block backporting.

samccann · 2022-01-10T18:40:42Z

I don't know if we want to backport this or not really. I know I'd like to keep this on devel only 'for a time' so we can get any feedback from users. I can put it in the bullhorn and on reddit etc once it's on devel. I was thinking it would go live on /latest/ with Ansible 6?

samccann · 2022-01-10T18:42:56Z

...or are you thinking of updating that docs-build.requirements in a separate PR? I'm still not sure we'd want our docs requirements out of sync with the sanity test...

felixfontein · 2022-01-10T18:48:19Z

I've now updated it in this PR. I'm not sure whether this is a problem, but now the dependencies for the docs build differ partially from the dependencies for the changelog test (https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/sanity.changelog.txt). @mattclay is this a problem (and do the requirements have to match), or is it ok if they differ?

samccann · 2022-01-10T18:51:27Z

Yeah it's picking up a lot of changes, most of which I don't know where they come from etc. Notice the ansible sphinx theme also got updated from what we use - https://github.com/ansible/ansible/pull/76675/files#diff-4cc37de5fc6a320124546ce84589725b60cf05237e02a49a19eaeda2f8f87fe2R37

Not sure what to do...

ansibot · 2022-01-10T19:17:01Z

The test ansible-test sanity --test docs-build [explain] failed with 1 error:

docs/docsite/rst/collections/ansible/builtin/default_callback.rst:343:0: warning: Unknown target name: "ansible".

The test ansible-test sanity --test test-constraints [explain] failed with 25 errors:

test/lib/ansible_test/_data/requirements/sanity.ansible-doc.txt:4:10: sanity constraint (==21.2) does not match others for package `packaging`
test/lib/ansible_test/_data/requirements/sanity.ansible-doc.txt:5:10: sanity constraint (==2.4.7) does not match others for package `pyparsing`
test/lib/ansible_test/_data/requirements/sanity.changelog.txt:2:20: sanity constraint (==0.12.0) does not match others for package `antsibull-changelog`
test/lib/ansible_test/_data/requirements/sanity.changelog.txt:4:10: sanity constraint (==21.2) does not match others for package `packaging`
test/lib/ansible_test/_data/requirements/sanity.changelog.txt:5:10: sanity constraint (==2.4.7) does not match others for package `pyparsing`
test/sanity/code-smell/docs-build.requirements.txt:8:20: sanity constraint (==0.13.0) does not match others for package `antsibull-changelog`
test/sanity/code-smell/docs-build.requirements.txt:14:19: sanity constraint (==2.0.10) does not match others for package `charset-normalizer`
test/sanity/code-smell/docs-build.requirements.txt:22:10: sanity constraint (==21.3) does not match others for package `packaging`
test/sanity/code-smell/docs-build.requirements.txt:25:9: sanity constraint (==2.11.2) does not match others for package `pygments`
test/sanity/code-smell/docs-build.requirements.txt:26:10: sanity constraint (==3.0.6) does not match others for package `pyparsing`
test/sanity/code-smell/docs-build.requirements.txt:29:9: sanity constraint (==2.27.1) does not match others for package `requests`
test/sanity/code-smell/docs-build.requirements.txt:35:16: sanity constraint (==2.2.0) does not match others for package `snowballstemmer`
test/sanity/code-smell/docs-build.requirements.txt:49:8: sanity constraint (==1.26.8) does not match others for package `urllib3`
test/sanity/code-smell/package-data.requirements.txt:2:20: sanity constraint (==0.12.0) does not match others for package `antsibull-changelog`
test/sanity/code-smell/package-data.requirements.txt:6:10: sanity constraint (==21.2) does not match others for package `packaging`
test/sanity/code-smell/package-data.requirements.txt:7:10: sanity constraint (==2.4.7) does not match others for package `pyparsing`
test/sanity/code-smell/rstcheck.requirements.txt:5:19: sanity constraint (==2.0.7) does not match others for package `charset-normalizer`
test/sanity/code-smell/rstcheck.requirements.txt:11:10: sanity constraint (==21.2) does not match others for package `packaging`
test/sanity/code-smell/rstcheck.requirements.txt:12:9: sanity constraint (==2.10.0) does not match others for package `pygments`
test/sanity/code-smell/rstcheck.requirements.txt:13:10: sanity constraint (==2.4.7) does not match others for package `pyparsing`
test/sanity/code-smell/rstcheck.requirements.txt:15:9: sanity constraint (==2.26.0) does not match others for package `requests`
test/sanity/code-smell/rstcheck.requirements.txt:17:16: sanity constraint (==2.1.0) does not match others for package `snowballstemmer`
test/sanity/code-smell/rstcheck.requirements.txt:25:8: sanity constraint (==1.26.7) does not match others for package `urllib3`
test/sanity/code-smell/update-bundled.requirements.txt:2:10: sanity constraint (==21.2) does not match others for package `packaging`
test/sanity/code-smell/update-bundled.requirements.txt:3:10: sanity constraint (==2.4.7) does not match others for package `pyparsing`

click here for bot help

mattclay · 2022-01-10T19:21:56Z

Manually update the pinned requirements in test/sanity/code-smell/docs-build.requirements.txt that changed.

It should be safe to do so as long as those package versions are compatible with the other pinned packages in that file.

Once this is merged I'll rebuild the test container used for the devel branch.

If it does get backported, there will be merge conflicts and I'll need to rebuild the container used in the stable-2.12 branch. I'd like to avoid that if we can, but if it's needed then that's OK.

mattclay · 2022-01-10T20:31:30Z

lib/ansible/plugins/doc_fragments/default_callback.py

@@ -18,9 +18,9 @@ class ModuleDocFragment(object):
        env:
          - name: DISPLAY_SKIPPED_HOSTS
            deprecated:
-              why: environment variables without "ANSIBLE_" prefix are deprecated
+              why: environment variables without C(ANSIBLE_) prefix are deprecated


Should the quote fixes be done in a separate PR so they can be independently backported?

Ah, I see you've already opened a PR for that.

Sorry, didn't mention it here, but I created a separate PR (#76698). I've now rebased after that one was merged.

…rce." (This needs to be done in a separate PR, since it also needs to modify the docs build sanity test. Backporting it follows different rules than pure docs build backports, so let's keep it separate.) This reverts commit 649a349.

felixfontein · 2022-01-10T21:32:06Z

@webknjaz @samccann @mattclay thanks for reviewing and testing!

webknjaz approved these changes Jan 7, 2022

View reviewed changes

felixfontein changed the title ~~Use antsibull 0.40.0 for docsite build~~ Use antsibull 0.40.1 for docsite build Jan 7, 2022

samccann approved these changes Jan 10, 2022

View reviewed changes

samccann suggested changes Jan 10, 2022

View reviewed changes

ansibot added needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. and removed core_review In order to be merged, this PR must follow the core review workflow. labels Jan 10, 2022

ansibot removed the docs_only All changes are to files within the docs/docsite/ directory label Jan 10, 2022

ansibot added needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. and removed core_review In order to be merged, this PR must follow the core review workflow. labels Jan 10, 2022

felixfontein mentioned this pull request Jan 10, 2022

Fix broken markup #76698

Merged

mattclay reviewed Jan 10, 2022

View reviewed changes

felixfontein added 6 commits January 10, 2022 21:40

Use antsibull 0.40.0 for docsite build.

ce234c2

Change deprecated --ansible-base-source to --ansible-core-source.

1171b95

Bump antsibull version to 0.40.1.

ee0904e

Bump (minimum) sphinx-ansible-theme version for docs build to 0.9.0.

a65b466

Manually update pinned versions for docs sanity test.

cea1f1f

felixfontein force-pushed the antsibull-upgrade branch from adcaea8 to cea1f1f Compare January 10, 2022 20:41

ansibot added core_review In order to be merged, this PR must follow the core review workflow. and removed needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. labels Jan 10, 2022

mattclay approved these changes Jan 10, 2022

View reviewed changes

ansibot added needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. and removed core_review In order to be merged, this PR must follow the core review workflow. labels Jan 10, 2022

samccann approved these changes Jan 10, 2022

View reviewed changes

samccann merged commit c53e6d9 into ansible:devel Jan 10, 2022

felixfontein deleted the antsibull-upgrade branch January 10, 2022 21:31

bcoca removed the needs_triage Needs a first human triage before being processed. label Jan 11, 2022

This was referenced Jan 12, 2022

remove outdated note on limitations of R() in module docs #76736

Merged

Bump antsibull version from 0.40.1 to 0.41.0 and ansible sphinx theme version to fix HTML generation in return value tables #76759

Merged

ansible locked and limited conversation to collaborators Jan 24, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use antsibull 0.40.1 for docsite build #76675

Use antsibull 0.40.1 for docsite build #76675

felixfontein commented Jan 7, 2022

felixfontein commented Jan 7, 2022

ansibot commented Jan 7, 2022

samccann left a comment

samccann left a comment •

edited

samccann commented Jan 10, 2022

felixfontein commented Jan 10, 2022

felixfontein commented Jan 10, 2022

samccann commented Jan 10, 2022

samccann commented Jan 10, 2022

felixfontein commented Jan 10, 2022

samccann commented Jan 10, 2022

ansibot commented Jan 10, 2022

mattclay commented Jan 10, 2022

mattclay Jan 10, 2022

mattclay Jan 10, 2022

felixfontein Jan 10, 2022

felixfontein commented Jan 10, 2022

Use antsibull 0.40.1 for docsite build #76675

Use antsibull 0.40.1 for docsite build #76675

Conversation

felixfontein commented Jan 7, 2022

SUMMARY

ISSUE TYPE

COMPONENT NAME

felixfontein commented Jan 7, 2022

ansibot commented Jan 7, 2022

samccann left a comment

Choose a reason for hiding this comment

samccann left a comment • edited

Choose a reason for hiding this comment

samccann commented Jan 10, 2022

felixfontein commented Jan 10, 2022

felixfontein commented Jan 10, 2022

samccann commented Jan 10, 2022

samccann commented Jan 10, 2022

felixfontein commented Jan 10, 2022

samccann commented Jan 10, 2022

ansibot commented Jan 10, 2022

mattclay commented Jan 10, 2022

mattclay Jan 10, 2022

Choose a reason for hiding this comment

mattclay Jan 10, 2022

Choose a reason for hiding this comment

felixfontein Jan 10, 2022

Choose a reason for hiding this comment

felixfontein commented Jan 10, 2022

samccann left a comment •

edited