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.
Related
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'm using Sphinx to document a python project, and I'm trying to create a reusable tip to be used in several locations.
Typically, I'll use the following syntax in a python file:
"""
.. tip::
I want this tip to be used in several locations. Why?
- Save time
- Work less
"""
Now this works whether I put it at the beginning of the file, right under class definition or right under function definition.
I found Sphinx's manual for :ref:, which suggests to use a label:
.. _my_reusable_tip:
.. tip::
...
And then call this tip with :ref:`my_reusable_tip` anywhere I want.
The manual states that 'it works across files, when section headings are changed, and for all builders that support cross-references'
The thing is, it doesn't matter in which .py file in the project I write the label and tip definition, the :ref:`my_reusable_tip` just displays 'my_reusable_tip', and not the tip itself.
What I'm using to build the documentation is
sphinx-apidoc -f -F -o
make html
I'm pretty sure my logic is flawed in some way, but I can't figure out why.
I know that Sphinx searches the project for reStructuredText and renders it if it can, but I think I'm missing something here.
I tried to add this label in a seperate .py file enclosed in """, and in a separate .txt file without enclosed """.
I tried creating an .rst file with the label definition and rebuild the html documentation.
What am I missing here?
Python 3.4.3 BTW.
In sphinx, a :ref: is simply a more robust way of linking (or referencing) another part of the document. Thus, your use of :ref: will simply provide a hyperlink to the label.
It is not a way of substituting or expanding a block.
Inline substitutions are available using using |...|, however an inline substitution cannot be used to substitute a block as you seem to require.
RestructuredText is not a template language, and thus doesn't provide macro like facilities. In the event you need it, an alternative solution is to use a template library such as mako or jinja to deal with this kind of issue.
Just using reStructuredText directive
.. include:: ./my_reusable_tip.txt
in your rst files?
We are planning on creating a user manual for our software project. Currently, everything related to the code is documented in Sphinx, and we would like to use Sphinx for the manual.
Since we are writing scientific/engineering software, there will be a lot of topics on things like stress, strain, numerical algorithms, etc. For each topic, we will have a few stages of information:
Basic information: This one or two sentence description can be used anywhere we need a short summary of the topic. Example: simple definition of mechanical stress.
More detailed description: This one paragraph explanation can be used as the opening to a help page, or a summary in a more detailed listing of topics. Example, a paragraph about mechanical stress introducing the equation for axial stress.
Technical information. This can be multiple paragraphs on how the topic applies to the problems encountered by users of our software.
Code information. This will be documentation related to where the topic is encountered in the code. For example, we can point to our implementation of a certain numerical algorithm. We can use sphinx-apidoc like we currently do.
As you can see, the information gradually gets more complex. We would like to manage each topic in their own .rst file, and get the required information as needed. For example, maybe we want to use the basic information section in a tooltip. In the actual help menu, we can use the detailed description in a table of contents on a certain class of topics. In the full article on the topic, like what would be present in a full pdf manual, we can present the technical information along with the basic and more detailed descriptions. Lastly, we would like to keep code information only in our internal documentation.
It would be nice to keep all of the information for a single topic in one file, but to conditionally compile different sections based on the documentation we are generating.
Is there a built-in way to do something like this in Sphinx? If someone is doing something similar, can you tell us about it and give us some highlights of your workflow?
In past I wanted to compile two docs, a public and a private but I didn't want to split my source file (rst).
First step I found the only directive and I thought it was the solution. But when I wanted a entire full rst file in just public or private documentation I can't without indent the whole file.
So I write my own Sphinx plugin (scope) to manage all my case. To succeed I used the meta directive that can be place on the top of the file.
Thus
a_doc_for_basic.rst
.. meta::
:scope: basic
Title
=====
My content
a_doc_for_code.rst
.. meta::
:scope: code
Title
=====
My content
And you can continue to use .. only:: directive on file
a_doc_for_all.rst
Title
=====
My content
.. only:: code
a piece of code
You can find plugin source here
As you can see the plugin is pretty simple and works thanks to regexp. That means (regexp) that there is limitation:
The directive .. meta:: :scope: must be place at the top of the file (no line before)
The directive .. meta:: :scope: must match the regexp ^\.\. meta::\s+:scope: ([a-zA-Z0-9_-]+)
The directive .. meta:: :scope: can manage multiple tag but you can easily update the plugin for your needs
Plugin deviate the original use of meta directive docutils.sourceforge.net/docs/ref/rst/directives.html#meta
After that you can build your doc using the following command
sphinx-build ... -t <tag> ...
sphinx-build ... -t code ...
Other thing, you can use the same toctree for all tag because when compiling a doc per tag the toctree will be edited by the plugin to generate a tree without reference to the no-matching documentation.
PS: my plugin is not perfect but I replied to my needs, you can inspired and update it.
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.
I would like to be able to parse sphinx based rst in Python for further processing and checking. Something like:
import sphinx
p = sphinx.parse("/path/to/file.rst")
do_something_with(p)
It seems that something is possible in docutils using the docutils.core.publish_file:
publish_file(open("/path/to/file.rst")
But that doesn't know anything about sphinx specific directives etc...
You can use Sphinx Extensions to do custom processing before the final write. There is a very good getting started example project in the documentation that discusses various hooks that allow you to customize Sphinx.
Depending on what you're trying to do, you may need to supply your do_something function as a call back argument to one of these events.
doctree-resolved(app, doctree, docname)
html-page-context(app, pagename, templatename, context, doctree)
And then you can extend sphinx as follows
def setup(app):
app.connect('doctree-resolved', do_something)
If the example in the Sphinx tutorial is not detailed enough, Doug Hellmann also has a blog post about creating a spell checker for Sphinx. I found it to be a useful reference for the Sphinx extension I had to write a while back.