I am new to Sphinx.
The file /home/user/myproject/docs/source/index.rst is as following:
My project contents:
.. toctree::
:glob:
*
I am getting the below message on running $ make html under /home/user/myproject/docs/:
checking consistency... /home/user/myproject/docs/source/design/index.rst:: WARNING: document isn't included in any toctree
What have I done wrongly? I would like Sphinx to automatically generate the structure depending on the directory hierarchy.
I don't think this is a supported operation.
Fortunately, it's not a very desirable one either, since you generally want the parts of your documentation to appear in a particular order.
If you are willing to just dump all your source files in source without a folder heirarchy, this is possible. Alternatively you could write a routine and run it from the Makefile before the call to sphinx-build.
As Mike alluded to, :glob: will just pull files in alphabetically by filename. See the docs here.
You can use “globbing” in toctree directives, by giving the glob flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically.
If you want to use :glob: and maintain ordering with all your files in source, you'll need to prefix your .rst files with numbers.
Example
source
├── index.html
├── 1_intro.rst
├── 2_install.rst
└── 3_more-than-you-want-to-know.rst
Though, you will of course need to rename the files if you decide you want them ordered differently, rather than moving the order of an explicit list in index.rst.
Related
I am generating documentation for a Python project using the Sphinx autodocsumm extension with the following autosummary configuration to show a summary of only classes at the beginning of the document.
Module1 module
----------------------------
.. automodule:: src.Module1
:members:
:undoc-members:
:show-inheritance:
:autosummary:
:autosummary-no-nesting:
In the generated html, the summary class name hyperlinks are not consistent -- one is a path to a separate summary stub file, while the other just references an anchor in the main src.html file.
file:///project_path/docs/_build/html/src.Module1/src.Module1.Class1.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2
I can't figure out why the classes are being treated differently during the make. The first one is a large class with many members while the second is a small class with just a few lines, so maybe there is some threshold for generating the stub file? My preference is to not reference a separate file and only jump to the respective anchor within the main document for all summary links.
Is there a setting to control this behavior?
Edit: Upon further review, I don't think this has anything to do with autodocsumm after all. I notice after doing the "make html" a subfolder is create only for the Class1 documentation while Class2 is referenced only in the main src.html file.
project_path/docs/_build/html/src.Module1/src.Module1.Class1.html
project_path/docs/_build/html/src.html
So... Why are these two classes treated differently? Also, is there any setting to prevent a separate folder and html file from being generated?
I finally figured out the issue... While narrowing my project down to a minimum reproducible example, I noticed an src.Module1 folder under docs that had rst files for Class1 only.
Project
docs
_build
src.Module1
Module1.Class1.rst
src.Module1.Class1.rst
I'm not sure what I did to produced that folder, but after deleting it and rebuilding the Sphinx html, I am now getting the document anchors I expect directly in the src.html file:
file:///project_path/docs/_build/html/src.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2
I have a project that I'm documenting where I've ended up with a structure like
docs/
conf.py
development/
architecture.rst
uimockups/
index.html
static/
<supporting css and js files>
mockup1/
index.html
ui1.html
ui2.html
mockup2/
index.html
ui1.html
ui2.html
Where everything under uimockups is just a static site. For organizational reasons I really want to keep the folder structure as is here, and would like to just copy uimockups to build/development/uimockups directly, that way I could link to it from my architecture.rst file.
I've searched around online, but most of what I can find is pertaining to the _static folder for customizing CSS and that sort of thing. All I want is to copy this entire folder to its corresponding location in the HTML build output. Is this possible without writing a custom extension? Can sphinx perform this simple task through configuration alone?
Well, I figured out a solution, but it isn't what I'd consider the best solution.
Since I wanted to be able to also do python -m http.server in the docs/development/uimockups folder and have it work, I ended up:
Renaming docs/development/uimockups/static to docs/development/uimockups/_static.
Changing all .html files to refer to files in ./_static or ../_static as appropriate instead of using an absolute /static path.
Adding 'development/uimockups' to the html_static_path variable in conf.py
This last step is the equivalent of adding cp development/uimockups/* $BUILD/_static/, so while not really ideal I end up with
$BUILD/
_static/
_static/ # From uimockups/
<supporting files>
index.html # From uimockups/
mockup1/
ui1.html
ui2.html
mockup2/
ui1.html
ui2.html
Then I can link to this with `link text </_static/index.html>`_ in my rst files.
I don't really like that I just have to shove this into the $BUILD/_static folder, and I can't just have it appear in $BUILD/development/uimockups instead, but this doesn't require me to write any code at least. It's definitely not scaleable though, if I had multiple "static sub-sites" then they would potentially step on each other's resources. One way to work around this would be to have
docs/
development/
uimockups-site/
uimockups/
index.html
mockup1/
mockup2/
_static/
And then add development/uimockups-site to my html_static_path list so that the output is
$BUILD/
_static/
uimockups/
index.html
mockup1/
mockup2/
_static/
You could add uimockups to html_extra_path in conf.py, and link to files in it as explained here.
I have a file layout that looks like:
/my_module
__init__.py
submodule1.py
submodule2.py
I use Sphinx's automodule directive like:
.. automodule:: my_module.submodule1
It produces documents that say my command name is something like: my_module.submodule1.my_function. But my __init__ pulls submodule1 into the my_module namespace. So what I really want is for the documentation to say my_module.my_function instead. Leave out the submodule1, since that's not what users are going to use.
Is there a way to do this?
Not exactly, but you can get close. There is the ~ (tilde) in standard cross-referencing syntax.
If you prefix the content with ~, the link text will only be the last component of the target. For example,
:py:meth:`~Queue.Queue.get`
will refer to Queue.Queue.get but only display get as the link text. This does not work with all cross-reference roles, but is domain specific.
You might be able to use substitutions or the raw directive, but that would bypass the advantage of using autodoc and its directives.
I'm using sphinx-apidoc and autosummary extensions to document an API for a library and I'm really unable to understand the purpose of the generated/ option below:
.. autosummary::
:nosignatures:
:toctree: generated/
module.function_1
module.function_2
...
I've seen this is the Sphinx documentation, and in libraries like pandas. I'm using toctree and my API is autogenerating, but I don't understand what generated is. I don't see a folder called generated, and don't know what the advantage/purpose of this is.
Thanks
The "generated" option is the name of the output directory where Sphinx puts automatically generated "stub" .rst files. It does not have to be called "generated"; you can use any name.
When the autosummary_generate configuration variable is set to True, Sphinx generates a .rst file for each entry listed in autosummary directives. For example, if you are documenting a module with several classes, this feature can be used to put the full documentation for each class on a separate page. The autosummary table will contain links to these pages.
When generating documentation using Sphinx, I would like to be able to generate two versions of my documentation: one including everything, and one with only a particular set of pages. What's the best way of achieving that?
I could write a build script that moves files around to achieve this but it would be really nice if there was a way to tell sphinx to exclude or include particular documents during a particular build.
Maybe my answer comes a bit late, but I managed to do this with Sphinx via exclude patterns in the config file.
My documentation is partly for users and partly for admins.
Some pages have file names that contain the word admin, and like you, I wanted to build two versions: one with everything (the admin docs) and one with all "admin" pages excluded (the user docs).
To exclude all "admin" pages in all subfolders, you have to add this line to the config file conf.py:
exclude_patterns = ['**/*admin*']
That was the easy part.
My problem was that I didn't know how to run the build two times, one with and one without the exclude patterns without using two different config files.
I didn't find a solution by myself, so I asked a question here on SO and got an answer:
The config file is just a Python file and can contain Python code, which will be executed on build.
You can pass parameters ("tags") via the command line which can be queried in the config file.
So I have this exclude pattern in my config file:
exclude_patterns = ['**/*admin*']
if tags.has('adminmode'):
exclude_patterns = []
Now I can run the build without passing anything, which will exclude the "admin" files:
make clean
make html
⇒ this is my user documentation
...and I can set the "adminmode" tag, which will not exclude anything:
(Windows command line syntax)
set SPHINXOPTS=-t adminmode
make clean
make html
⇒ this is my admin documentation.
Bonus:
I can use the same tag to ignore some specific content on a page, by Including content based on tags.
Example:
regular documentation
=====================
This paragraph and its headline will always be visible.
.. only:: adminmode
secret admin stuff
------------------
This paragraph will be visible in the admin docs only.
This will (again) always be visible.
The only and ifconfig directives can be used to apply conditions within pages.
There does not seem to be any simple way to use conditions to completely exclude entire pages (.rst files).
The following (in index.rst) excludes the reference to doc2.html in the toctree in index.html when generating HTML output:
.. toctree::
doc1.rst
.. only:: latex
.. toctree::
doc2.rst
But this does not really work. The doc2.html file is still generated, and it is reachable via the "Next topic" link when doc1.html is the current topic.
How about sphinx.ext.ifconfig? You set config values in your conf.py file. As that is a regular Python file, you can make your inclusion criteria smart and automatic if you need to.