The Sphinx templates I use (for example sphninxdoc or sphinx13) have a link to a 'contents.rst' file; however, though this file is documented as "special", I don't see a way to generate it.
Is there a way to get Sphinx to generate 'contents.rst' automatically, or do I need to generate it manually?
When I came to this page, I needed to fix the .readthedocs.yml. My sphinx configuration path was missing the "source" part:
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
Within the config, I have
# The master toctree document.
master_doc = 'index'
The "special" contents.rst file that is mentioned in the question is not generated automatically. It is written like any other reST file and is stored in the Python repository: https://github.com/python/cpython/blob/master/Doc/contents.rst.
The Python documentation main page at http://docs.python.org/release/2.7/index.html has a Complete Table of Contents link that points to contents.html, which is built from contents.rst.
The source for the Sphinx documentation includes a similar contents.rst: https://github.com/sphinx-doc/sphinx/blob/master/doc/contents.rst.
Related
I have a medium-sized python project that I'm currently documenting using sphinx with the autodoc extension. I have the basics down, the generated documentation looks reasonable.
I have now come across an interesting documentation problem: I have some JSON input file that contains configuration of some sorts. It contains several sections that are used in different parts of my application. I figured the best way to keep the documentation up to date is to document configuration options as close to the point of their usage as possible.
On the other hand, I'd really like to have a single page describing the complete input file structure.
I figured it would be nice if I could somehow "transclude" the relevant documentation blocks into this page so that it shows up both in this page and within the respective module documentation pages like so:
a.py:
def fn_using_A():
'''documentation for config parameter paramA
'''
pass
b.py
def fn_using_B():
'''documentation for config parameter paramB
'''
The input file format documentation page should look somewhat like this:
paramB
------
documentation for config parameter paramB
paramA
------
documentation for config parameter paramA
I would like to not have links/references to the respective functions/modules/whatever but a verbatim copy of the documentation without having to actually copy the documentation into the respective .rst file.
It would be even better to only transclude a part of the documentation I can mark somehow within my code documentation.
I tried using reST's replace feature, writing
def fn_handling_C():
'''fn documentation
.. |paramC_documentation| replace:: foo bar baz
'''
in my code and using |paramC_documentation| within the .rst file that documents my input file format, but generating the documentation yields an error message to the effect that the replacement pattern isn't known. That doesn't surprise me since autodoc doesn't generate full .rst files for modules which are parsed together with manually written .rst files.
Is there a way to achieve this with sphinx?
I ended up writing my own sphinx extension. I used sphinx-todo as basis and modified that to my liking.
My program’s documentation is mainly written in Sphinx, but it also includes two custom HTML pages:
an example report produced by the program;
an extended reference on certain features of the program.
These two HTML files are produced by the program itself, not by Sphinx.
I want to host my docs on Read the Docs, and it would be very convenient for me to build and host the two custom pages, versioned, together with the Sphinx docs.
My program is already installed in the RtD build environment as I have the Install Project option enabled. And since the RtD docs mention writing your own builder, I gather it might be possible to invoke my program from there and have it dump the HTML content in a specific place.
So I really have two questions:
Is this an appropriate use of Read the Docs? I guess it’s not designed to host arbitrary Web pages — but then again, those files are not arbitrary, they are an important part of the docs.
How would I implement it? I’m having a hard time making sense of the RtD API: is this “builder” related in any way to Sphinx builders? how do I hook it up to RtD? perhaps there is an example somewhere?
I achieved the desired result using Sphinx’s html_extra_path feature:
A list of paths that contain extra files [...] They are copied to the output directory.
To generate these files, I haven’t found a better place than right in my conf.py, which seems a bit precarious, but works so far. Of course, Install your project inside a virtualenv needs to be enabled in Read the Docs advanced settings.
Now my custom notices.html and showcase.html are treated just like the .html pages produced by Sphinx itself, with versioning and redirects: http://httpolice.readthedocs.io/page/notices.html
I have set up a Sphinx documentation for my project and would like to extract doc strings for the source files and embed them into the final documentation. Unfortunately, the source file's language (VHDL) is not supported by Sphinx. There seems to be no Sphinx domain for VHDL.
So my ideas is as follows:
Hook into the Sphinx run and execute some Python code before Sphinx
The Python codes extracts text blocks from each source file (the top-most multi-line comment block) and assembles one reST file per source file, consisting of this comment block and some other reST markup.
All source files are listed in an index.rst, to generate the apropriate .. toctree:: directive.
The text extraction and transformation is done recursively per source code directory.
So the main question is: How to hook into Spinx?
Or should I just import and run my own configuration in conf.py?
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
from my_preprocessor import my_proc
proc = my_proc()
proc.run()
#
# Test documentation build configuration file, created by
# sphinx-quickstart on Tue May 24 11:28:20 2016.
# ....
I can't modify the build process files: Makefile and make.bat, because the real build process runs on ReadTheDocs.org. RTDs only executes conf.py.
As noted in my previous comments and mertyildiran's answer, the official way to hook into Sphinx for a language would be to create an extension to implement a new domain for VHDL.
This has already been done for many other languages - e.g. Erlang, PHP, CoffeeScript - and APIs - e.g. HTTP REST - just to name a few from sphinx-contrib. However, that is going to take a lot of time, which you don't have... You are therefore left with an option to do some quick parsing yourself and then hooking that into your Sphinx build somehow.
Since you are bypassing the official hooks, this question becomes "how do I run my own code inside a Sphinx build?" For which, I would recommend that you simply follow the guidance for a local extension - i.e. put it in a separate directory, add that to your path, then import and invoke it. As noted in the docs:
The configuration file is executed as Python code at build time (using execfile(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.
As a final though, this opens up the options to use 3rd party packages like pyVhdl2Sch (with a nod again to mertyildiran's answer) to create some schematic and then maybe write your static rst files around it to explain the schematic.
You are trying to use a sledgehammer to crack a nut.
Sphinx was originally created for the new Python documentation, and it has
excellent facilities for the documentation of Python projects, but
C/C++ is already supported as well, and it is planned to add special
support for other languages as well.
http://www.sphinx-doc.org/en/stable/
VHDL is currently not a supported language by Sphinx and because VHDL is a hardware description language its priority for becoming a supported language must be low. You have two options and first one is also my suggestion to you:
1) Use a VHDL specific documentation generator tool instead of Sphinx
VHDocL -
http://www.volkerschatz.com/hardware/vhdocl.html
A VHDL documentation utility written in Perl, based on Doxygen.
pyVhdl2Sch - http://laurentcabaret.github.io/pyVhdl2Sch/
pyVhdl2Sch is a documentation generator tool. It takes VHDL files (.vhd) as entry and generates a pdf/svg/ps/png schematic for each input file. Written in pure Python, more community friendly, more up to date.
Sigasi Studio XL Doc - http://www.sigasi.com/products/
High end edition of Sigasi Studio which is a commercial product.
2) Contribute to Sphinx project and add VHDL domain
Follow Sphinx Developer's Guide and become familiar with the project structure. Eventually add vhdl.py to this project directory: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains
This second option cannot be explained with a StackOverflow answer. It's up to you if you want to add more functionality to an open source project like Sphinx.
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.