Use requirements.txt to install prereqs for docs build (#65709)
* Use requirements.txt to install prereqs for docs build * implement feedback
This commit is contained in:
parent
f76dded9c6
commit
80f5503ed0
1 changed files with 20 additions and 3 deletions
|
@ -51,8 +51,9 @@ A great documentation GitHub issue or PR includes:
|
|||
- a detailed description of the problem (even for a PR - it's hard to evaluate a suggested change unless we know what problem it's meant to solve)
|
||||
- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on.)
|
||||
|
||||
Before you open a complex documentation PR
|
||||
==========================================
|
||||
|
||||
Verifying your documentation PR
|
||||
================================
|
||||
|
||||
If you make multiple changes to the documentation, or add more than a line to it, before you open a pull request, please:
|
||||
|
||||
|
@ -60,6 +61,12 @@ If you make multiple changes to the documentation, or add more than a line to it
|
|||
#. Test your changes for rST errors.
|
||||
#. Build the page, and preferably the entire documentation site, locally.
|
||||
|
||||
|
||||
Setting up your environment to build documentation locally
|
||||
----------------------------------------------------------
|
||||
|
||||
To build documentation locally, ensure you have a working :ref:`development environment <environment_setup>`.
|
||||
|
||||
To work with documentation on your local machine, you need to have python-3.5 or greater and the
|
||||
following packages installed:
|
||||
|
||||
|
@ -75,9 +82,18 @@ following packages installed:
|
|||
- sphinx-notfound-page
|
||||
- straight.plugin
|
||||
|
||||
These required packages are listed in two :file:`requirements.txt` files to make installation easier:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install --user -r requirements.txt
|
||||
pip install --user -r docs/docsite/requirements.txt
|
||||
|
||||
You can drop ``--user`` if you have set up a virtual invironment (venv/virtenv).
|
||||
|
||||
.. note::
|
||||
|
||||
On macOS with Xcode, you may need to install ``six`` and ``pyparsing`` with ``--ignore-installed`` to get versions that work wth ``sphinx``.
|
||||
On macOS with Xcode, you may need to install ``six`` and ``pyparsing`` with ``--ignore-installed`` to get versions that work with ``sphinx``.
|
||||
|
||||
.. _testing_documentation_locally:
|
||||
|
||||
|
@ -183,4 +199,5 @@ The Documentation Working Group is just getting started, please visit the `commu
|
|||
|
||||
.. seealso::
|
||||
:ref:`More about testing module documentation <testing_module_documentation>`
|
||||
|
||||
:ref:`More about documenting modules <module_documenting>`
|
||||
|
|
Loading…
Reference in a new issue