I want to use Sphinx as a documentation generator. When I try to run the make html command, I have the following error :
Extension error:
Could not import extension sphinxcontrib.httpdomain (exception: No module named sphinxcontrib.httpdomain)
make: *** [html] Error 1
I've found this web page explaining that I have to manually add the extension to the Sphinx configuration file https://pythonhosted.org/sphinxcontrib-httpdomain/#module-sphinxcontrib.httpdomain
But I can't find this configuration file.
Do you have any idea where I could find it ? I'm on Mac OS X
The configuration is in the source folder of your Sphinx project. It is named conf.py and contains an extensions option which should look like this:
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
...
]
Related
How can I tell readthedocs not to load any Python files located at top root folder?
Background: I would like readthedocs to build Sphinx documentation for a Blender Python add-on, hosted on github. I have created docs folder in the repository for Sphinx files. I can build Sphinx docs OK on my local computer (in docs directory), but the build on readthedocs fails on error
File "/home/docs/checkouts/readthedocs.org/user_builds/bvtknodes/envs/latest/lib/python3.7/site-packages/pip/_internal/utils/misc.py", line 20, in <module>
from pip._vendor import pkg_resources
File "/home/docs/checkouts/readthedocs.org/user_builds/bvtknodes/envs/latest/lib/python3.7/site-packages/pip/_vendor/pkg_resources/__init__.py", line 41, in <module>
import inspect
File "/home/docs/checkouts/readthedocs.org/user_builds/bvtknodes/checkouts/latest/inspect.py", line 1, in <module>
import bpy
ModuleNotFoundError: No module named 'bpy'
The reason for this error was that there was inspect.py module located at root directory, so readthedocs setup process loaded that instead of system version of inspect module. When I renamed my inspect.py to b_inspect.py, then the docs building process finished properly at readthedocs. However this is just a workaround, is there a better solution?
Original wrong interpretation: It seems that readthedocs is trying to inspect __init__.py (located at top folder level and can't be moved from there to a subfolder) contents and build fails when it can't import bpy. AFAIK there is no way to install bpy module via pip (but I wouldn't want to do that anyway). I'd like readthedocs to ignore all python files. language = None and extensions list in docs/conf.py is empty. I've also set "Python configuration file" setting in readthedocs Advanced Settings to docs/conf.py. Thanks!
Here is link to readthedocs build which failed.
I am new to Sphinx and I want to write a documentation of a Python package. I have a problem when I want to include a demonstration file.
I want to include the file demo.ipynb using the extension nbsphinx. It is successfully installed on my computer. The extensions variable in my conf.py file for Sphinx contains the following lines:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
'sphinx.ext.napoleon',
'nbsphinx',
]
and the toctree in my index.rst is the following:
.. toctree::
:maxdepth: 3
:glob:
demo
when I compile my documentation I always obtain the following warning:
PATHTOPACKAGE/docs/source/index.rst:19: WARNING: toctree contains reference to document 'demo' that doesn't have a title: no link will be generated
Does Sphinx maybe try to include the file as .rst file? The nbsphinx documentation just says that I have to install the package, add nbsphinx to the extensions and that I will then be able to add my documents to the toctree. I didn't find any information related to this problem.
I just ran in into this again and noticed that you need to make sure that your source_suffix config does not include .ipynb.
So the conf.py should look like this
extensions = [
# ...,
"nbsphinx"
]
source_suffix = [".rst", ".md"]
# note: do not add .ipynb when nbspinx is enabled, otherwise you get the "missing title" error
On top of that, you need to make sure that the notebook contains a title, as already pointed out in the answers above.
Each notebook needs a title.
Just create a Markdown cell in your notebook with something like this in it:
# My Title
See also https://github.com/spatialaudio/nbsphinx/issues/310 and https://github.com/spatialaudio/nbsphinx/pull/401.
There is now a better warning, see https://github.com/spatialaudio/nbsphinx/pull/402.
I used the sphinx-quickstart to set everything up. I used doc/ for the documentation root location. The folder containing my package is setup as:
myfolder/
doc/
mypackage/
__init__.py
moprob.py
...
After the quick start, I edited the path in conf.py to be:
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
Then I added one of the scripts in my package to index.rst to see how Sphinx works.
.. toctree::
:maxdepth: 2
:caption: Contents:
mypackage/moprob
The error code I get:
.../index.rst:9: WARNING: toctree contains reference to nonexisting document u'mypackage/moprob'
Solutions I have tried:
Adding sphinx.ext.napoleon to the extensions list since all of my doc strings are written using the NumPy format. The error did not go away. I also put the napoleon extension after autodoc because one of the documentation pages suggested that.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.napoleon']
Adding numpydoc_show_class_members = False to conf.py. I put this directly below the extensions but it also did not solve the error.
A couple of different configurations for folder locations. I've also tried setting the root location to be /myfolder and setting the source to be /mypackage and the build to be /doc. None has worked.
The toctree directive contains references to reStructuredText documents, not Python scripts or modules. Sphinx expects there to be a mypackage/moprob.rst file (in the doc folder), but there isn't one. Hence the error.
To quickly get some meaningful output, create the mypackage/moprob.rst file. Add a heading and an automodule directive in it:
moprob module
=============
.. automodule:: mypackage.moprob
:members:
Then run sphinx-build again.
I created a private Python package that requires an XML file. When I run the package locally and on CircleCi, everything works great. Now, when I run code that installs the package as a dependency, I keep getting an error:
<urlopen error [Errno 2] No such file or directory: '/home/ubuntu/virtualenvs/venv-system/local/lib/python2.7/site-packages/...../metadata_wsdl.xml'>
Does anyone know what could be wrong? I have not been able to figure this one out.
You need to explicitly include any resources that aren't Python source code (*.py) in your setuptools distribution.
There are several ways to do this. The one I'd recommend is to use a combination of include_package_data = True in your setup() function and a MANIFEST.in file.
So assuming your distribution is layed out as my.package/my/package (i.e., with no intermediate src or lib directory), you could use something along these lines:
setup.py
from setuptools import setup, find_packages
setup(
...
packages = find_packages('my'), # include all packages under my/
include_package_data = True, # include everything in source control
# or included in MANIFEST.in
)
MANIFEST.in
recursive-include my *
recursive-include docs *
global-exclude *.pyc
global-exclude ._*
global-exclude *.mo
This would recursively include any type of file below my.package/my/ as well as my.package/docs/, and globally exclude some other types of files unwanted in a released distribution.
Please refer to Building and Distributing Packages with Setuptools ยป Including Data Files for more details on the available methods to include data files, and The MANIFEST.in template for more information about how to define your MANIFEST.
Once you've successfully included your data files in your distribution, you should make sure to use the ResourceManager API to access them from your code (as opposed to __file__ trickery or other path hacks, which won't work for certain platforms or zipped eggs).
I want to install some HTML on-line doc that is made (understand compiled from rSt) using sphinx along with the python code into the site-package. I want to to this using setup.py.
To be more specific, I want to complile my *.rst files to HTML and then copy then into site-package from the setup.py file when the user types python setup.py install.
Does someone know how to do this ? I look into sphinx and setuptools doc but was not able to find the info.
The reason I want to do it, is that my package is a GUI tool and the HTML is the on-line help of it. It is displayed into GUI's internal browser.
As already noted you'll need a MANIFEST.in file to include the docs directory:
recursive-include docs *
Now in your setup.py you could programmatically generate the sphinx documentation from your *.rst files.
Here's an example on how to do that automatically when python setup.py install is run:
from distutils.core import setup
# set dependencies, we need sphinx to build doc
dependencies = ['sphinx']
setup(
name='my_package'
# rest of your setup
)
# auto-generate documentation
import sphinx
# automatically build html documentation
# For example:
# format = 'html'
# sphinx-src-dir = './doc'
# sphinx-build-dir = './doc/build'
sphinx.build_main(['setup.py', '-b', '<format>', '<sphinx-src-dir>', '<sphinx-build-dir>'])
Like this you can run sphinx-build as needed (Documentation).
Note: It might be a good idea to add a Custom command to your setup.py for separating documentation generation (f.e. python setup.py make_doc [params]) and install routine (python setup.py install). This way the user could easily supply parameters format, sphinx-src-dir and sphinx-build-dir.
You can add them into your MANIFEST.in and then build the package
recursive-include docs *
Then it will be distributed with your egg