From 0a0b3401af6a4c35fd567b4e7d157c1602ad0497 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 24 Jan 2023 22:31:47 -0600 Subject: [PATCH 1/2] Overhaul Building the Documentation section for clarity --- documentation/start-documenting.rst | 128 +++++++++++++++++----------- 1 file changed, 79 insertions(+), 49 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 175c73c0a..fbcb497ca 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -64,79 +64,109 @@ Building the documentation .. highlight:: bash -The toolset used to build the docs is written in Python and is called Sphinx_. -Sphinx is maintained separately and is not included in this tree. Also needed -are blurb_, a tool to create :file:`Misc/NEWS` on demand; and -python-docs-theme_, the Sphinx theme for the Python documentation. +To build the documentation, follow the steps in one of the sections below. +You can view the documentation after building the HTML +by opening the file :file:`Doc/build/html/index.html` in a web browser. -To build the documentation, follow the instructions from one of the sections -below. You can view the documentation after building the HTML by pointing -a browser at the file :file:`Doc/build/html/index.html`. +.. note:: -You are expected to have installed the latest stable version of -Sphinx_ and blurb_ on your system or in a virtualenv_ (which can be -created using ``make venv``), so that the Makefile can find the -``sphinx-build`` command. You can also specify the location of -``sphinx-build`` with the ``SPHINXBUILD`` :command:`make` variable. + The following instructions all assume your current working dir is + the ``Doc`` subdirectory in your :ref:`CPython repository clone `. + Make sure to switch to it with ``cd Doc`` if necessary. -.. _building-using-make: +.. _doc-create-venv: + +Create a virtual environment +---------------------------- -Using make / make.bat ---------------------- +.. _doc-create-venv-unix: -**On Unix**, run the following from the root of your :ref:`repository clone -` to build the output as HTML:: +**On Unix platforms** that support :program:`make` +(including Linux, macOS and BSD), +you can create a new :mod:`venv` with the required dependencies using:: - cd Doc make venv - make html -or alternatively ``make -C Doc/ venv html``. ``htmlview`` can be used -instead of ``html`` to conveniently open the docs in a browser once the -build completes. +Building the docs with :program:`make` will automatically use this environment +without you having to activate it. + +.. _doc-create-venv-windows: + +**On Windows**, or if not using :program:`make`, +`create a new virtual environment `__ manually. +Always be sure to `activate this environment `__ +before building the documentation. + + +.. _building-using-make: +.. _using-make-make-bat: +.. _doc-build-make: + +Build using Make / make.bat +--------------------------- -You can also use ``make help`` to see a list of targets supported by -:command:`make`. Note that ``make check`` is automatically run when -you submit a :ref:`pull request `, so you should make -sure that it runs without errors. +A Unix ``Makefile`` is provided, :cpy-file:`Doc/Makefile`, +along with a :cpy-file:`Doc/make.bat` batch file for Windows +that attempts to emulate it as closely as practical. -**On Windows**, the :cpy-file:`Doc/make.bat` batchfile tries to emulate -:command:`make` as closely as possible, but the venv target is not implemented, -so you will probably want to make sure you are working in a virtual environment -before proceeding, otherwise all dependencies will be automatically installed -on your system. +.. important:: -When ready, run the following from the root of your :ref:`repository clone -` to build the output as HTML:: + The Windows ``make.bat`` batch file lacks a ``make venv`` target, + automatically installing any missing dependencies + into your current environment. + Make sure the environment you `created above `__ + is `activated `__ before running ``make.bat``. + +To build the docs as HTML, run:: - cd Doc make html -You can also use ``make help`` to see a list of targets supported by -:cpy-file:`Doc/make.bat`. +.. tip:: Substitute ``htmlview`` for ``html`` to open the docs in a web browser + once the build completes. + +To check the docs for common errors with `sphinx-lint`_ +(which is run on all :ref:`pull requests `), use:: + + make check + +To list other supported :program:`Make` targets for your platform, run:: + + make help + +See :cpy-file:`Doc/README.rst` for more information. + + +.. _using-sphinx-build: +.. _doc-build-sphinx: + +Build using Sphinx directly +--------------------------- + +Advanced users may want to invoke Sphinx directly, +to pass specialized options or to handle specific use cases. -See also :cpy-file:`Doc/README.rst` for more information. +First, ensure the environment you `created above `__ +is `activated `__. +Then, install the documentation requirements, :cpy-file:`Doc/requirements.txt`. +Using pip:: -Using sphinx-build ------------------- + python -m pip install --upgrade -r requirements.txt -Sometimes we directly want to execute the sphinx-build tool instead of through -``make`` (although the latter is still the preferred way). In this case, you can -use the following command line from the ``Doc`` directory (make sure to install -Sphinx_, blurb_ and python-docs-theme_ packages from PyPI):: +Finally, directly invoke Sphinx with:: - sphinx-build -b . build/ + python -m sphinx -b html . build/html -where ```` is one of html, text, latex, or htmlhelp (for explanations -see the make targets above). +To use a different `Sphinx builder`_, +replace ``html`` above with the desired builder ``name``. .. _docutils: https://docutils.sourceforge.io/ -.. _python-docs-theme: https://pypi.org/project/python-docs-theme/ .. _Sphinx: https://www.sphinx-doc.org/ -.. _virtualenv: https://virtualenv.pypa.io/ -.. _blurb: https://pypi.org/project/blurb/ +.. _Sphinx builder: https://www.sphinx-doc.org/en/master/usage/builders/index.html +.. _sphinx-lint: https://github.com/sphinx-contrib/sphinx-lint +.. _venv-activate: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment +.. _venv-create: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment Style Guide From 5f4ccf247bc95a1e342a22281a67ee3927471847 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Wed, 25 Jan 2023 22:45:59 -0600 Subject: [PATCH 2/2] Apply suggestions and further clarifications from Hugo Co-authored-by: Hugo van Kemenade --- documentation/start-documenting.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index fbcb497ca..592059bf7 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -103,7 +103,7 @@ before building the documentation. .. _using-make-make-bat: .. _doc-build-make: -Build using Make / make.bat +Build using make / make.bat --------------------------- A Unix ``Makefile`` is provided, :cpy-file:`Doc/Makefile`, @@ -112,10 +112,10 @@ that attempts to emulate it as closely as practical. .. important:: - The Windows ``make.bat`` batch file lacks a ``make venv`` target, - automatically installing any missing dependencies - into your current environment. - Make sure the environment you `created above `__ + The Windows ``make.bat`` batch file lacks a ``make venv`` target. + Instead, it automatically installs any missing dependencies + into the currently activated environment (or the base Python, if none). + Make sure the environment you :ref:`created above ` is `activated `__ before running ``make.bat``. To build the docs as HTML, run:: @@ -125,12 +125,12 @@ To build the docs as HTML, run:: .. tip:: Substitute ``htmlview`` for ``html`` to open the docs in a web browser once the build completes. -To check the docs for common errors with `sphinx-lint`_ +To check the docs for common errors with `Sphinx Lint`_ (which is run on all :ref:`pull requests `), use:: make check -To list other supported :program:`Make` targets for your platform, run:: +To list other supported :program:`make` targets, run:: make help @@ -146,7 +146,7 @@ Build using Sphinx directly Advanced users may want to invoke Sphinx directly, to pass specialized options or to handle specific use cases. -First, ensure the environment you `created above `__ +Make sure the environment you :ref:`created above ` is `activated `__. Then, install the documentation requirements, :cpy-file:`Doc/requirements.txt`. Using pip:: @@ -164,7 +164,7 @@ replace ``html`` above with the desired builder ``name``. .. _docutils: https://docutils.sourceforge.io/ .. _Sphinx: https://www.sphinx-doc.org/ .. _Sphinx builder: https://www.sphinx-doc.org/en/master/usage/builders/index.html -.. _sphinx-lint: https://github.com/sphinx-contrib/sphinx-lint +.. _Sphinx Lint: https://github.com/sphinx-contrib/sphinx-lint .. _venv-activate: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment .. _venv-create: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment