Skip to content

Commit

Permalink
fix problems with building the documentation
Browse files Browse the repository at this point in the history
robert-lieck committed Jun 2, 2022

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent aebc120 commit 390d507
Showing 3 changed files with 8 additions and 5 deletions.
6 changes: 1 addition & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -111,13 +111,9 @@ The `docs` folder contains a skeleton documentation using the [Read the Docs Sph
For local builds, you can run `make` commands in the `docs` directory (you will have to install the packages specified in `docs/requirements.txt`), in particular
- `make html`: builds the documentation
- `make doctest`: runs all code examples in the documentation and checks if the actual output matches the one shown in the documentation
- `make clean`: remove all built files (except `_autosummary`, see below)
- `make clean`: remove all built files (including `_autosummary` and `auto_examples`)
- `make help`: get information about available make commands.

To automatically generate a detailed API, the Sphinx extension `autosummary` is used, which may cause some trouble:
- You may get `WARNING: duplicate object description ...`.
- The generated files are stored inside `_autosummary`, which is not cleaned up by `make clean`, so you have to manually remove those files.

#### Publish via GitHub Pages

To publish the documentation via GitHub pages, you have to:
6 changes: 6 additions & 0 deletions doc/Makefile
Original file line number Diff line number Diff line change
@@ -17,6 +17,12 @@ help:

.PHONY: help Makefile

# Remove build directory, examples, and autosummary files
clean:
rm -rf $(BUILDDIR)/*
rm -rf auto_examples/
rm -rf _autosummary/

# Auto rebuild with sphinx-autobuild
livehtml:
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1 change: 1 addition & 0 deletions doc/index.rst
Original file line number Diff line number Diff line change
@@ -19,6 +19,7 @@ Code examples are automatically tested

.. autoclass:: pythontemplatepackage.myclass.MyClass
:members:
:noindex:


.. Indices and tables

0 comments on commit 390d507

Please sign in to comment.