(Note: this is similar to Conditional output in Sphinx Documentation, but it's not clear if the solution there is usable.)
I have some documentation of two functions that are very similar. What I want to write is a file that would be included by the doc for both that looks like:
.. if:: doc_for_foo
This documentation only applies to ``foo``.
.. if:: doc_for_bar
This documentation only applies to ``bar``.
This documentation applies to both.
So, the common content would appear in two separate pages of the same generated documentation. Is there a way to do this? (I know about .. only, but it isn't clear how I would enable the relevant bits for each documentation page.)
Note: I don't want to just split the common stuff into separate files, because the content is significantly interleaved. That is, I would end up with:
Text about ``foo``.
.. include:: common-part-1
More text.
.. include:: common-part-2
.. for 'foo', no intervening text here
.. include:: common-part-3
More text.
.. include:: common-part-4
...and so on, where each part is perhaps a single paragraph. IOW, the former would be much easier to maintain.
To clarify, I want something like:
.. foo.rst
.. enable-tag:: doc_for_foo
.. include:: foo_and_bar_doc
.. bar.rst
.. enable-tag:: doc_for_bar
.. include:: foo_and_bar_doc
...where both foo.rst and bar.rst are generated by the same run of Sphinx. Passing -t at build time won't work; both foo.rst and bar.rst would (AFAIU) see the same set of tags set. Same with anything I did in conf.py.
Related
I am using Sphinx and ReStructuredText to create documentation, but even though all pages were created the same way, only 4 out of 8 are showing on the side menu. This is my table of contents:
.. toctree::
:glob:
:titlesonly:
*
I've tried to add the pages manually, but it didn't seem to work either.
Here's the link to the documentation where you can find the source code: Docs
You should use either correct syntax of the toctree directive when using its options, or use file names whose casing aligns with what you put in the toctree directive.
The .rst files in your directory are the following.
Coordenadas.rst
Galeria-mapa.rst
Home-page.rst
Lista-camadas.rst
index.rst
legenda.rst
marcador.rst
medicao.rst
oscilar.rst
But in your index.rst you use the incorrect case for those filenames, and you add a blank line between the file names and glob character without using the glob option.
.. toctree::
Home-page
Coordenadas
Galeria-mapa
Legenda
Lista-camadas
Marcador
Medicao
Oscilar
*
By looking at the build log on Read The Docs, you would find several warnings indicating what went wrong.
/home/docs/checkouts/readthedocs.org/user_builds/documentation-senografia/checkouts/latest/docs/source/index.rst:5: WARNING: toctree contains reference to nonexisting document 'Legenda'
To fix it, this is one option.
.. toctree::
Home-page
Coordenadas
Galeria-mapa
legenda
Lista-camadas
marcador
medicao
oscilar
And this should work, too. Note that in this version compared to yours, the options are immediately after the toctree directive without a blank line between them. A blank line should be present before the first toctree entry.
.. toctree::
:glob:
:titlesonly:
*
I am new to Sphinx and I don't seem to find the way to achieve this. I want to be able to quickly comment/uncomment single toctree entries as I progress, without having to remove the line. I use to do this in Latex to reduce the compilation time while my project is still in progress.
For instance, I'd like to achieve something like this:
.. toctree::
file1
file2
.. file3 (I want to comment/uncomment this, easily)
file4
.. file5 (this also fails)
..
file6 (this also fails)
What is the right way to do it?
Have you tried using the :hidden: option under the toctree directive?
I image you'd need to have two separate toctree directives to achieve this though:
.. toctree::
visiblefile1
visiblefile2
.. toctree::
:hidden:
hiddenfile1
hiddenfile2
See also sphinx-doc.org.
Perhaps this achieves acceptable results. Its not exactly commenting/uncommenting, but it achieves the same result.
It seems I might have found something close to a solution (the closest so far). It consists of putting the .. unindented, that is, at the same level as the toctree directive. For instance, I get something like this:
.. toctree::
Title 1 <file1>
Title 2 <file2>
Title 4 <file4>
.. the comment starts here
Title 3 <file3>
Title 5 <file5>
etc
And having this, the best approach to 'comment/uncomment' I can get is by selecting the target line and drag&droping it into the commented/uncommented area, respectively.
I have a module with several classes. Currently I am using ..automodule to document the module. I'd like each class to have its own header section with the class name. I could achieve this by replacing ..automodule foo with:
Bar
===
..autoclass foo.Bar
Baz
===
..autoclass foo.Baz
...
However, that would require me to manually list every class in every module I do this for. What is the best way to customize the content generated by automodule?
Sphinx is not as straightforward to use as Epydoc or Doxygen for generating API documentation from source code. It is a dfferent kind of tool.
Sphinx works on .rst (reStructuredText) files, and if you want each class to have its own heading with the class name, you have to add the headings yourself and use .. autoclass::. It cannot be done with just .. automodule::. Yes, this is inconvenient (similar sentiments are expressed here). See also this answer and this answer.
The problem can be mitigated by a script that walks through the Python code and generates .rst output. Sphinx already comes with such a script, sphinx-apidoc. However, it does not produce any .. autoclass:: directives, only .. automodule::.
Here is another script that can output .. autoclass::: https://github.com/PyMVPA/PyMVPA/blob/master/tools/apigen.py. Maybe you can use that.
I have the following page at plugins/index.html:
Plugin Development
==================
.. toctree::
:hidden:
basics/index
advanced/index
The Basics
----------
- :doc:`basics/gettingstarted`
- :doc:`basics/resources`
- :doc:`basics/i18n`
Advanced Topics
---------------
- :doc:`advanced/models`
- :doc:`advanced/controllers`
- :doc:`advanced/services`
plugin/basics/index.html and plugins/advanced/index.html contain their own toctree’s, which link to the same subpages listed in plugins/index.html. So what I’m wondering is, is there a way to just include those sub toctree’s, rather than manually listing the sub pages out like I’m doing?
I realize that I could just remove the :hidden: flag from the toctree, but the point is I want to keep Basic/Advanced topics in separate lists, with their own headings, intro paragraphs, etc.
You can list the entire directory contents like this (or various combinations of these directives):
.. toctree::
:glob:
:titlesonly:
:maxdepth: 2
**
or I think also like this (untested):
.. toctree::
:glob:
:titlesonly:
:maxdepth: 2
*
basics/*
advanced/*
However, I have found just manually listing things is often the best way to go. While the automatically generated TOCs are nice, they don't allow you much room in terms of formatting (for example, creating sub headings, and changing the order of pages etc).
In our documentation I have done pretty much the same thing you did in the initial question.
In Sphinx, if I have the following heading declaration:
.. _somestuff:
``this is code``, this is not!
==============================
It renders, like this:
this is code, this is not!
Which is good, but, if I use the reference, e.g:
Have a look at :ref:`somestuff`
It loses the code formatting and renders like:
Have a look at this is code, this is not!
instead of:
Have a look at this is code, this is not!
Is it possible to retain the code formatting in the reference? And how would I go about it?
If you have a look at :ref: documentation in its official web site about inline markups:
:ref:
To support cross-referencing to arbitrary locations in any document,
the standard reST labels are used. For this to work label names must
be unique throughout the entire documentation ...
I think (as #Kevin Horn) it's no possible right now, because it's only used to create links (without rst formatting) with other sections in your project. Then if you write something like this:
.. _somestuff:
``this is code``, this is not!
==============================
.. _another_somestuff:
this is another code!
========================
If I link with these sections:
Have a look at :ref:`somestuff`
Have a look at :ref:`another_somestuff`
Have a look at :ref:`this link <somestuff>`
The result is:
Have a look at this is code, this is not!
Have a look at this is another code!
Have a look at this link
The style is the same in all of them .
Note: the italic/bold words symbolize links