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.
Related
This question is about sphinx-nested-apidoc (not sphinx-apidoc).
After running
sphinx-nested-apidoc -o docs/source mymodule/
I am having a structure as follows:
source/
|──index.rst
|──module.rst
|──mymodule
|──index.rst
|──some_function.rst
|──subfolder
|──index.rst
|──another_function.rst
The module.rst which was automatically generated contains:
mymodule
====
.. toctree::
:maxdepth: 4
mymodule
So I call modules.rst in index.rst and run
.\make.bat html
and get the warning
docs\source\modules.rst:4: WARNING: toctree contains reference to nonexisting document 'mymodule'
I understood that this is somehow related to the fact that mymodule is a folder but toctree expects a .rst file.
I am a little bit confused why sphinx-nested-apidoc creates the mymodule folder and calls it into the toctree in module.rst.
What can I do so that the .rst files in the mymodule folder are recognized?
The path to the master doc of a Sphinx build can be specified in conf.py. However, this directory path is reflected in the generated HTML, and shows for example in Read The Docs as a missing index. I'd like to use this alternative path to structure my project cleanly - to have configuration at the top level and documentation inside src, but have the build essentially get rid of it.
So here's what I had previously:
docs
conf.py
index.rst
things
doc1.rst
doc2.rst
This works, but when lots of files are added to the top level, it gets messy with Sphinx's makefiles etc. I'd like to have this instead:
docs
conf.py
src
index.rst
things
doc1.rst
doc2.rst
Which builds, but index.html is in build/html/src instead of build/html. I was surprised to find no information on this, other than the fact that master_doc in conf.py controls the location and name of the main file. How could I get my documentation to be built to build/html?
There is an option for specifying the location of the configuration file: -c.
# conf.py
master_doc = 'index'
# structure
docs
conf.py
src
index.rst
...
Then run sphinx-build -b html -c . src build/html. However, this solution indeed needs control over the build command, which is not available in Read The Docs. And it seems that -c doesn't work in Sphinx's own makefiles either (with -M instead of -b).
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 am not able to add my __main__.py file correctly and its functions while generating RST file with sphinx-apidoc. Other files and classes are generated correctly.
I works only if I run sphinx-apidoc with -P parameter which includes private modules. But I do not want to add private methods of other modules, I need these from __main__.py only.
__main__.py looks like this:
def main():
"""
main() description here
"""
f1()
f2()
if __name__ == '__main__':
main()
I would like to have main(), f1() and f2() included in RST files generated by sphinx-apidoc.
There is a similar question Documenting python script entry (__name__ == '__main__') using sphinx but it does not answer my question.
I think this is an undocumented feature, or a it can also be bug in sphinx-apidoc v.3.2.1. If we look at the documentation for -P option, it reads:
-P, --private
Include “_private” modules.
Notice this doesn't mention :private-members: from autodoc flag options.
Two different issues are conflated, "private modules" and "private objects inside a module". The options that impact .rst file generation should be different for each according to the official documentation.
sphinx-apidoc will generate the .rst files based of 2 main templates, module.rst_t and package.rst_t. (Using Sphinx with a venv on Windows these are found under /venv/Lib/site-packages/sphinx/templates/apidoc).
The default behaviour (implemented by the templates) is to generate 1 .rst file per package, and within that file place 1 .. automodule:: directive per module. What the -P option does (supposedly) is to add one more directive .. automodule:: your-package.__private-module__ to the .rst file per private module.
An alternative is using -e option with sphinx-apidoc in which case a separate .rst file is generated for each module and package. So using sphinx-apidoc -e -P will cause an extra .rst file to be generated for private modules.
But I do not want to add private methods of other modules
Private classes/methods/variables (objects inside a module) are impacted by the autodoc ':private-members:' option.
sphinx-apidoc sets the default autodoc options of the generated .. automodule:: directives as defined by the SPHINX_APIDOC_OPTIONS environment variable (namely, :members:, :undoc-members: and show-inheritance). These options can't be passed as a command line argument, you have to set the environment variable before running sphinx-apidoc to change the default values. (sphinx-apidoc does not take them from conf.py, unlike autodoc.)
Looking at the source code of apidoc.py
# automodule options
if 'SPHINX_APIDOC_OPTIONS' in os.environ:
OPTIONS = os.environ['SPHINX_APIDOC_OPTIONS'].split(',')
else:
OPTIONS = [
'members',
'undoc-members',
# 'inherited-members', # disabled because there's a bug in sphinx
'show-inheritance',
]
Because :private-members: is a default autodoc options that should be set using SPHINX_APIDOC_OPTIONS (as documentation states and source code shows). If you include the -P option, its only (documented) effect should be adding .. automodule:: directives for private modules, what does happen is that it also sets the autodoc option :private-members: on each directive.
The following tree:
your_package
├ one_module.py
├ __init__.py
└ __main__.py
With sphinx-apidoc -P will generate:
your_package.__main__ module
----------------------------
.. automodule:: your_package.__main__ <<-- -P option is documented as having this effect.
:members:
:undoc-members:
:show-inheritance:
:private-members: <<-- -P option is not documented to have this effect.
So how to achieve the stated aim in the question?
If you use -e option with sphinx-apidoc generating one .rst file per module, you could use the [EXCLUDE_PATTERN …] from the signature. By running sphinx-apidoc twice, once for the __main__.py modules (together with -P option), and a second time for the remaining modules.
If you don't want individual .rst files for you modules, but instead the normal 1 .rst file for each package containing one directive per module. Then there is no practical possibility of achieving that (without resorting to considerable hacking). Your best choice is simply copy-pasting 1 .. automodule:: directive per __main__.py into the .rst files after they are generated.
I use sphynx to generate documentation from static .rst files (no docstrings extraction).
I have two files in my repository:
index.rst
.. toctree::
intro
and intro.rst
Will be skipped
===============
Where is my parent section?
---------------------------
Second section
==============
Below is screenshot of pdf obtained by running sphinx-build -b latex . _build; cd _build; pdflatex * :
Flabbergasting or what?
Thanks for providing the working example. I can reproduce your observation with Sphinx 1.2.3 on Windows. As far as I can see, the HTML output is working as expected. With the LaTeX builder, the following document structure is produced:
\chapter{Where is my parent section?}
\label{intro:will-be-skipped}\label{intro::doc}\label{intro:where-is-my-parent-section}
\chapter{Second section}
\label{intro:second-section}
I found suspicious about your document that it did not define a title. As a workaround I have found that adding a higher hierarchy works, whereas it does not matter if you put it into index.rst or intro.rest. This is the modified index.rst:
=====
TITLE
=====
.. toctree::
intro
Resulting in:
I have then further looked out for this problem, and found this Bitbucket/GitHub issue dealing with the very same issue (it is from 2011):
https://bitbucket.org/birkenfeld/sphinx/issue/632/section-versus-chapter-oddity-in-latex
https://github.com/sphinx-doc/sphinx/issues/632
Quote:
Your index.rst doesn't have a title, right? Basically Sphinx gobbles
up the most toplevel title (which is then replaced by the document
frontmatter).
That issue was put "on hold" back in 2011, probably it was not considered failing behavior. It was then just recently closed on GitHub without being "fixed". So, as Georg wrote in that ticket, Sphinx indeed just consumes the highest hierarchy whereas its content does not appear anywhere.
Therefore: adding a "title hierarchy", no matter how you name it, is the proper solution.
Using Ubuntu 14.04 and texlive if I create a new Sphinx project with sphinx-quickstart (separate source and build directories), drop the example files into the source directory and build with:
$ make latexpdf
I see the see the Will be skipped heading in the PDF output.
The OPs original command was
$ sphinx-build -b latex . _build; cd _build; pdflatex *
to build the documentation, which is slightly different than the latexpdf target in the Makefile which uses latex all-pdf. However, if I create a new project directory with the same conf.py that sphinx-quickstart created I still see the Will be skipped output in the PDF using the OPs command sequence. I would look into the conf.py settings that you are using, those might give a clue to the solution.