From eb070f504c496002c2812f0d4b6763761b88d910 Mon Sep 17 00:00:00 2001 From: gabalafou Date: Wed, 22 Jan 2025 18:01:37 -0600 Subject: [PATCH 1/2] Add instructions to the docs on how to build the docs locally --- CONTRIBUTING.rst | 4 ++++ doc/source/dev/building_extension.rst | 4 ---- doc/source/dev/how_to_build_the_docs.rst | 25 ++++++++++++++++++++++++ doc/source/dev/index.rst | 1 + 4 files changed, 30 insertions(+), 4 deletions(-) create mode 100644 doc/source/dev/how_to_build_the_docs.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 82d5cb38a..9af62290f 100644 --- a/CONTRIBUTING.rst +++ b/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 diff --git a/doc/source/dev/building_extension.rst b/doc/source/dev/building_extension.rst index 193e7cca4..6ffcd0f6c 100644 --- a/doc/source/dev/building_extension.rst +++ b/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 -------------------------------- diff --git a/doc/source/dev/how_to_build_the_docs.rst b/doc/source/dev/how_to_build_the_docs.rst new file mode 100644 index 000000000..763c344f8 --- /dev/null +++ b/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. diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index 23a15747d..970a611c8 100644 --- a/doc/source/dev/index.rst +++ b/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? From 8067126cf3ef693c84be4881f5c5dfbf911d7e78 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Fri, 24 Jan 2025 18:27:59 +0100 Subject: [PATCH 2/2] DOC: fix readthedocs build error by adding path to conf.py --- .readthedocs.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 16fdddfd7..8487d46ff 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,3 +9,6 @@ python: - requirements: util/readthedocs/requirements.txt - method: pip path: . + +sphinx: + configuration: doc/source/conf.py