Fix Sphinx warnings when building the documentation #185
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sphinx would print the following warning and omit the link to
the "Initial tagging" section:
docs/source/commandline.rst:9: WARNING: undefined label: command line usage (if the link has no caption the label must precede a section header)
This is fixed by using the heading's implicit hyperlink target
instead of a ref role.
Sphinx would print the following warning and generate and empty
"Filter" page:
docs/source/implementation.rst:18: WARNING: autodoc: failed to import class u'Filter' from module u'afew.Filter'; the following exception was raised:
The Filter class is now defined in the afew.filters.BaseFilter
module.
Sphinx would print the following warning and would be unable to
reference libnotmuch's Python bindings:
WARNING: intersphinx inventory 'http://packages.python.org/notmuch/objects.inv' not fetchable due to <class 'requests.exceptions.HTTPError'>: 404 Client Error: Not Found for url: https://pythonhosted.org/notmuch/objects.inv
The documentation of libnotmuch's Python bindings is available
on readthedocs.io. Also use HTTPS and don't refer to an
end-of-life version of Python.
When being run in an environment where afew was not already
installed Sphinx would print the following warnings:
docs/source/implementation.rst:11: WARNING: autodoc: failed to import class u'Database' from module u'afew.Database'; the following exception was raised:
docs/source/implementation.rst:18: WARNING: autodoc: failed to import class u'Filter' from module u'afew.Filter'; the following exception was raised:
docs/source/implementation.rst:24: WARNING: autodoc: failed to import module u'afew.Settings'; the following exception was raised:
docs/source/implementation.rst:27: WARNING: autodoc: failed to import module u'afew.NotmuchSettings'; the following exception was raised:
docs/source/implementation.rst:34: WARNING: autodoc: failed to import module u'afew.utils'; the following exception was raised:
Sphinx needs to be made aware of the location to the source
code so it can find the Python modules even when they aren't
installed already. This is required when the documentation is
built in a clean environment such as when creating packages for
operating systems.
This fixes afewmail#184.
|
Hey @seschwar |
GuillaumeSeren
approved these changes
Mar 11, 2018
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
When building the documentation Sphinx warns about several things, which lead to certain omissions in the generated documentation. This pull request fixes these. Refer to the individual commit messages for the details.
This among others fixes #184.