Skip to content

Add an --outdated flag to the build_docs.py script, which sets the 'outdated' value within HTML templates. #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 2 commits into from
Closed

Add an --outdated flag to the build_docs.py script, which sets the 'outdated' value within HTML templates. #86

wants to merge 2 commits into from

Conversation

leonardr
Copy link

@leonardr leonardr commented Apr 11, 2020 •
edited
Loading

This branch supports work on python/steering-council#3.

My cpython PR python/cpython#19229 adds a header to the top of each documentation page if the outdated variable is set. This branch changes the build process so that the outdated variable is set automatically for 2.7 releases when building the full set of documentation. The outdated variable can also be set when building a single release, using the --outdated command-line flag.

I've never used this script before, so I tried a number of strategies to test this change. For all of these I used specially created subdirectories to store the logs, checkouts, and HTML output, rather than using the defaults in /srv/ and /var/. I also passed my own user group as group since I don't have a docs group on my machine.

  1. To test the command-line arguments, I verified that this command passes -A outdated=1 as one of the SPHINXOPTS:

./build_docs.py --group=leonardr --log-directory=logs --www-root=output --languages en --branch=2.7 -q -o --build-root=../versions/

Here's the relevant output (my addition is bolded):

DEBUG:Running command ['make', '-C', '/home/leonardr/programming/psf/versions/2.7/cpython-en/Doc', 'PYTHON=/home/leonardr/programming/psf/versions/venv/bin/python', 'SPHINXBUILD=/home/leonardr/programming/psf/versions/venv/bin/sphinx-build', 'BLURB=/home/leonardr/programming/psf/versions/venv/bin/blurb', 'VENVDIR=/home/leonardr/programming/psf/versions/venv', 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q -A outdated=1', 'SPHINXERRORHANDLING=', 'autobuild-stable-html']

  1. To test the default behavior of this script -- iterating over different versions of Python -- I ran this command:

./build_docs.py --group=leonardr --log-directory=logs --www-root=output -q -o --build-root=../versions/

All versions of the Python 2.7 docs were built with -A outdated=1:

DEBUG:Running command ['make', '-C', '/home/leonardr/programming/psf/versions/2.7/cpython-en/Doc', 'PYTHON=/home/leonardr/programming/psf/versions/venv/bin/python', 'SPHINXBUILD=/home/leonardr/programming/psf/versions/venv/bin/sphinx-build', 'BLURB=/home/leonardr/programming/psf/versions/venv/bin/blurb', 'VENVDIR=/home/leonardr/programming/psf/versions/venv', 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q -A outdated=1', 'SPHINXERRORHANDLING=', 'autobuild-stable-html']

Docs for other versions of Python were not:

DEBUG:Running command ['make', '-C', '/home/leonardr/programming/psf/versions/3.9/cpython-zh-tw/Doc', 'PYTHON=/home/leonardr/programming/psf/versions/venv/bin/python', 'SPHINXBUILD=/home/leonardr/programming/psf/versions/venv/bin/sphinx-build', 'BLURB=/home/leonardr/programming/psf/versions/venv/bin/blurb', 'VENVDIR=/home/leonardr/programming/psf/versions/venv', 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc=\\usepackage{xeCJK} -q -D locale_dirs=/home/leonardr/programming/psf/versions/3.9/locale -D language=zh_TW -D gettext_compact=0', 'SPHINXERRORHANDLING=', 'autobuild-dev-html']

  1. Since this script clones the primary branch for each version of cpython, and my 2.7 change has not been merged yet, I couldn't do a complete end-to-end test. Instead I checked out my cpython branch and then ran the make command generated by this script to verify that the banner shows up when -A outdated=1 is passed in on the command line.

make -C /home/leonardr/programming/psf/versions/2.7/cpython-en/Doc PYTHON=/home/leonardr/programming/psf/versions/venv/bin/python SPHINXBUILD=/home/leonardr/programming/psf/versions/venv/bin/sphinx-build BLURB=/home/leonardr/programming/psf/versions/venv/bin/blurb VENVDIR=/home/leonardr/programming/psf/versions/venv 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q -A outdated=1' SPHINXERRORHANDLING= autobuild-stable-html

Here's a visual of the final result:

image

This was referenced Apr 11, 2020
Closed
Merged
@benjaminp
Copy link
Contributor

We can remove automatic updates of the 2.7 documentation and simply serve a static generated output for the 2.x docs. So, I don't think the script needs to know about the outdated parameter.

@leonardr
Copy link
Author

leonardr commented Apr 18, 2020 •
edited
Loading

Thanks for the review. I'm not sure whether you're referring to the command-line parameter --outdated or the outdated parameter as passed into Sphinx. If the former, I agree we don't need this branch at all and I'll close it. If the latter, I've pushed a change that removes the --outdated command-line argument. -A outdated=1 is now only set when iterating over all releases.

To test this I ran the script like so:

./build_docs.py --group=leonardr --log-directory=logs --www-root=output -q --build-root=../versions/

The make command for Python 2.7 versions included -A outdated=1:

['make', '-C', '/home/leonardr/programming/psf/versions/2.7/cpython-en/Doc', 'PYTHON=/home/leonardr/programming/psf/versions/venv/bin/python', 'SPHINXBUILD=/home/leonardr/programming/psf/versions/venv/bin/sphinx-build', 'BLURB=/home/leonardr/programming/psf/versions/venv/bin/blurb', 'VENVDIR=/home/leonardr/programming/psf/versions/venv', 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q -A outdated=1', 'SPHINXERRORHANDLING=', 'autobuild-stable-html']

The make command for other versions of Python did not:

['make', '-C', '/home/leonardr/programming/psf/versions/3.8/cpython-en/Doc', 'PYTHON=/home/leonardr/programming/psf/versions/venv/bin/python', 'SPHINXBUILD=/home/leonardr/programming/psf/versions/venv/bin/sphinx-build', 'BLURB=/home/leonardr/programming/psf/versions/venv/bin/blurb', 'VENVDIR=/home/leonardr/programming/psf/versions/venv', 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q', 'SPHINXERRORHANDLING=', 'autobuild-dev-html']

@benjaminp
Copy link
Contributor

Thanks for the review. I'm not sure whether you're referring to the command-line parameter --outdated or the outdated parameter as passed into Sphinx. If the former, I agree we don't need this branch at all and I'll close it.

I mean the former. We'll just remove automatic rebuilding of 2.7 docs soon, since there will be no new changes to display.

Thank you for the PR, though.

@leonardr
Copy link
Author

Got it, thanks.

@leonardr leonardr closed this Apr 19, 2020
@leonardr leonardr deleted the outdated-flag branch April 19, 2020 21:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@leonardr @benjaminp