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).
Related
I have an existing project with the following directory structure:
docs/
conf.py
Makefile
index.rst
documentation-foo.rst
documentation-bar.rst
src/
...code...
common.mk
Makefile
README.rst
In the root of the repository, the Makefile contains various useful commands related to making, testing, packaging, and deploying the code. Likewise, common.mk includes a check to make sure the user has several utility programs available on their system (e.g., jq for manipulating/displaying JSON) that cannot be installed with pip. I can issue commands like make lint or make test and those are defined in that Makefile. (The top of the Makefile also has an include common.mk, see below for Makefile contents.)
In the docs/ folder, the Makefile is automatically generated by Sphinx. This Makefile is standalone and is totally independent of the Makefile or common.mk files in the root of the repository. I can issue commands like make html and it will use Sphinx to generate the documentation in HTML format.
Contents of (root) /Makefile:
include common.mk
clean:
...
lint:
...
test:
....
Contents of (root) /common.mk:
ifeq ($(shell which jq),)
$(error Please install jq using "apt-get install jq" or "brew install jq")
endif
Contents of (sphinx) /docs/Makefile:
# Minimal makefile for Sphinx documentation
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
...
My primary question is this: how can I incorporate the rules from the sphinx Makefile at /docs/Makefile so that they are available from the root level /Makefile?
For example, to make HTML documentation, I currently have to cd docs && make html from the root of the repo, but I would like to be able to run make html from the root of the repo and have the Makefile in the root of the repo resolve the target to the html target defined in docs/Makefile and use the rule defined in that Makefile.
Second, related question: if I have commands in docs/Makefile that have relative paths, must the paths be updated to be relative to the location where the make command is being run (the root of the repo instead of docs/), or does make resolve relative links to be relative to the Makefile's location in docs/?
You can do this with recursive make:
html:
$(MAKE) -C docs html
Some people strongly dislike recursive make. You can read the arguments against it, but I don't believe they apply to your use of make, since you're not trying to express dependencies.
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 am using sphinx-build to create both html and latexpdf output. Output looks amazing in both cases.
I would like to pass the project name on the command-line so the documentation can be titled e.g., TEST. This works great for the html option. In the example below (from a modified make.bat file), TEST overrides any project definition in the conf.py file.
%SPHINXBUILD% -b html -D project ="TEST" %ALLSPHINXOPTS% %BUILDDIR%/html
However, the command–line option is ignored when the tex file is created and whatever was in the conf.py is used for the definition of project in the generated PDF file.
%SPHINXBUILD% -b latexpdf -D project ="TEST" %ALLSPHINXOPTS% %BUILDDIR%/html
For example, if project is defined in conf.py: project = 'TEST'
Then used in the preamble: \title{project}
The document is titled TEST. I cannot seem to override the TEST value with a command-line argument.
Thanks for the reference to latex_elements. I realize that what I was trying to do, override settings in conf.py on the fly by using command-line arguments, is not going to work.
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.
I understand that the following generates rst for all modules, excluding the index.rst
sphinx-apidoc -f -o very_good_docs/ very_good
And the following generates everything, including index.rst, conf.py, Makefile, etc
sphinx-apidoc -F -f -o very_good_docs/ very_good
The problem is that sphinx-apidoc does not generate a correct conf.py, so I have to always manually modify conf.py to include the correct sys.paths. If I modify my python code in "very_good" folder, I should run the sphinx-apidoc command without "-F", so conf.py is preserved. However, if I add a new module under very_good directly, index.rst is not updated without the "-F" option, which means my new module will not be in the doc. I guess the solution is to either someone generates the index.rst file only, or using "-F" option without overriding the conf.py. Is there a way to do it?
This is something I'm experiencing right now. It's really frustrating not finding information to achieve something so common.
My approach is to use a custom config.py and specifying it always I execute sphinx-build with the -F option. This way my config.py is not overwritten even if a new (and useless) config.py is created.
In order to specify a custom config.py you should use the -c option as stated in the documentation:
-c path
Don’t look for the conf.py in the source directory, but use the given configuration directory instead. Note that various other files and paths given by configuration values are expected to be relative to the configuration directory, so they will have to be present at this location too.
New in version 0.3.
The command will look like this:
sphinx-build -b html -c %sphinxConfigDir% %sourceCode% %buildDir%