zhangyiss/spack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Tuneup docs re setting up sphinx for building docs (#14005)

Browse Source 
I have, more than once, tried to install the list of things that need
to build the docs, only to discover that the list doesn't use Spack's
package names.  I'm tired of facepalming....

While I was there I touched up the prose about activating the new
Python packages; activating a python package doesn't add anything to
your PYTHONPATH, it links things into a directory that's *already* on
your PYTHONPATH.  Note that this all presupposes that you're using
that same python....
This commit is contained in:
George Hartzell 2019-12-08 14:22:25 -08:00 committed by Adam J. Stewart
parent aa8d5d2e8c
commit 1d06949306
1 changed files with 14 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
lib/spack/docs/contribution_guide.rst
View File

@ -223,8 +223,7 @@ documentation. In order to prevent things like broken links and missing imports,
we added documentation tests that build the documentation and fail if there we added documentation tests that build the documentation and fail if there
are any warning or error messages. are any warning or error messages.
Building the documentation requires several dependencies, all of which can be Building the documentation requires several dependencies:
installed with Spack:
* sphinx * sphinx
* sphinxcontrib-programoutput * sphinxcontrib-programoutput
@ -234,11 +233,18 @@ installed with Spack:
* mercurial * mercurial
* subversion * subversion
All of these can be installed with Spack, e.g.
.. code-block:: console
$ spack install py-sphinx py-sphinxcontrib-programoutput py-sphinx-rtd-theme graphviz git mercurial subversion
.. warning:: .. warning::
Sphinx has `several required dependencies <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/py-sphinx/package.py>`_. Sphinx has `several required dependencies <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/py-sphinx/package.py>`_.
If you installed ``py-sphinx`` with Spack, make sure to add all of these If you're using a ``python`` from Spack and you installed
dependencies to your ``PYTHONPATH``. The easiest way to do this is to run: ``py-sphinx`` and friends, you need to make them available to your
``python``. The easiest way to do this is to run:
.. code-block:: console .. code-block:: console
@ -246,8 +252,10 @@ installed with Spack:
$ spack activate py-sphinx-rtd-theme $ spack activate py-sphinx-rtd-theme
$ spack activate py-sphinxcontrib-programoutput $ spack activate py-sphinxcontrib-programoutput
so that all of the dependencies are symlinked to a central location. so that all of the dependencies are symlinked into that Python's
If you see an error message like: tree. Alternatively, you could arrange for their library
directories to be added to PYTHONPATH. If you see an error message
like:
.. code-block:: console .. code-block:: console