Merge pull request #786 from gabalafou/how-to-build-docs

Add instructions to the docs on how to build the docs locally

Author: rgommers

.readthedocs.yaml

@@ -9,3 +9,6 @@ python:
     - requirements: util/readthedocs/requirements.txt
     - method: pip
       path: .
+
+sphinx:
+  configuration: doc/source/conf.py

CONTRIBUTING.rst

@@ -43,6 +43,8 @@ Coding guidelines
     provided in tutorial format and/or in module docstrings.  A guide on how to
     write documentation is given in the `numpydoc docstring guide`_.
 
+    Looking for `how to build the docs`_?
+
 3. Code style
     Uniformity of style in which code is written is important to others trying
     to understand the code.  PyWavelets follows the standard Python guidelines
@@ -64,3 +66,5 @@ Coding guidelines
 .. _pyflakes: http://pypi.python.org/pypi/pyflakes
 
 .. _testing guidelines: https://github.com/numpy/numpy/blob/main/doc/TESTS.rst.txt
+
+.. _how to build the docs: ./doc/source/dev/how_to_build_the_docs.rst

doc/source/dev/building_extension.rst

@@ -20,10 +20,6 @@ To verify the installation run the following command::
 
     pytest .
 
-To build docs::
-
-    cd doc
-    make html
 
 Installing a development version
 --------------------------------

doc/source/dev/how_to_build_the_docs.rst

@@ -0,0 +1,25 @@
+.. _dev-building-docs:
+
+How to build the docs locally
+=============================
+
+After preparing your Windows or Linux environment, install Spin and Ninja::
+
+    pip install spin ninja
+
+Then install the documentation-related dependencies::
+
+    pip install -r util/readthedocs/requirements.txt
+
+Then tell Spin to build the Sphinx documentation::
+
+    spin docs
+
+Then open a webserver to serve the built HTML files::
+
+    python -m http.server -d doc/build/html 8000
+
+And open your local docs in a web browser by visiting http://localhost:8000/.
+
+If it's your first time building the docs, it will take a while but should go
+faster on subsequent re-builds.

doc/source/dev/index.rst

@@ -17,6 +17,7 @@ on Windows and Linux.
    installing_build_dependencies
    building_extension
    testing
+   how_to_build_the_docs
    how_to_release
 
 Something not working?