I would line to auto number code-blocks in reStructuredText, if auto numbering is not possible then name/number them manually.
.. code-block:: python
:name: super awesome code exaple no 5
a = 1
When in training we can then reference them and tell students on witch example we now work on. We don't need to reference them in the document itself.
Is it possible in any way? Out of box or by extending Sphinx?
It is possible to do that via extending Sphinx.
You have to create your own extension (see how to create an extension and where to put your own extension) which will implement you new custom directive (see how to create a directive).
Directives are usual Python classes, so your NamedCodeBlock directive class should extend the CodeBlock directive class (see sphinx.directives.code.CodeBlock) and add support for the name optional argument where you will be able to set names for your code blocks.
Related
I'm rather new to Sphinx and ReST and I've "inherited" a big project.
The documentation consists of hundreds of pages with how to's, etc. There are several files (one for each class) where the respective functions are described using the ".. py:function::" directive.
So each of these pages is basically like this:
Some description text explaining the class
py:function:: class.myFunction(param1, param2)
parameter description
code example, ...
py:function:: class.myFunction2
parameter description
code example, ...
Now, I'd like to list all functions of all different pages in one single XML file, if possible grouped by their class, but without the descriptions and examples. Is this possible with some built-in Sphinx parser or do I have to write my own? Or is there any other directive or config option that may be helpful?
The XML file should be like this:
<class1>
<function1>
<param1>
<param2>
...
<function2>
...
<class2>
<function1>
...
I found ViewLists and the Parsing directive in the Sphinx documentation but i'm not sure how to correctly use them and if that's the solution to my problem.
I want to use the .. include:: function inline, but I can only get it to actually include the file I want if I separate it with two new lines from the previous text.
Before anyone asks, the file I want to include is a protocol number, so no, it doesn't benefit from a new line, at all. I want to be able to change it easily so I can use it on multiple places of my documentation. I guess that an example would be "We currently use the protocol (proto.txt)." I'm new to Sphinx and rst, so maybe there is a very obvious solution I haven't found.
Inline includes are not possible with Sphinx.
However, you can define global aliases (substitutions) in the rst_epilog variable of your build configuration file.
For example, you can add the following lines to your conf.pyfile:
rst_epilog = """
.. |version| replace:: 4.1
.. |protocol| replace:: httpx
"""
Now, you can access the variables |version| and |protocol| from any .rst file within your project, for example like this:
Version |version| uses the |protocol| protocol.
becomes
Version 4.1 uses the httpx protocol.
If other parts of your software require protocol (or other variables) to be specified in a specific file or format, you can write a script to read it from there as a variable into the Sphinx configuration file.
Is it possible to get Sphinx to generate the index based on existing labels and :ref: in the text? Say if you have a label:
.. _my_label:
My Section
and later refer to it through multiple :ref:`my_label` , is there a way to get the equivalent of an automatic generation of:
.. index:: My Section
where the label is, and the same before the paragraph where the :ref: lives?
The official doc does not list labels or :ref: as index-generating markup and I could not find any extension doing it. But maybe there is one?
There's an official list of Sphinx extensions, and there are a few lists of unoffical extensions on Github but none of them implement the functionality specified in the question.
The closest approach to the problem specified in the question would be using autosectionlabel to automatically create a target label having the section name, and place an :index: or .. index:: adjacent to the reST section to place it in the index. However, this would only save having to declare the label, declaring the index entry would still be necessary.
The functionality (directive) you ask for provides little tangible gain beyond writing one less line or block of reST code (the .. index:: directive or :index: role), be it for sections or targets.
Sphinx being open source would allow implementing a custom directive for this, however using a non-standard directive having as only aim shortening standard syntax by a single construct would stand to create more difficulty than gain for readers of your source code.
I am struggling with this issue:
I have to document a fairly large project composed by a C core engine and different API that are built on top of that, say Java, Python C#.
The docs must be deployed separately for each API, i.e. for each language, but 99% of the docs are the same, just the code snippet and example mainly need to change.
I set the type of language in the conf.py file by defining a global variable
I have used primary_domain and highlight_language to set the correct syntax highlighting
For each example I have a source file with the same name but different extension
Now, I'd like to include say an example using the literalinclude directive specifying the name of the file and let its extension change depending on the language in use. I tried naively to use the replace macro but with no success:
rst_prolog = ".. |ext| replace:: .%s\n" % primary_domain
correctly replace |ext| around the docs, but not in the command
.. literalinclude: filename|ext|
Is there any way I can do this, except parse rst files using sed or the like?
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.