I installed the sphinxcontrib-plantuml extension which works fine if I run the HTML builder e.g. with following testmodule.rst file for a corresponding testmodule.py file:
testmodule module
=================
.. automodule:: testmodule
:members:
:undoc-members:
:show-inheritance:
.. uml::
Alice -> Bob: Hi!
Alice <- Bob: How are you?
This adds the UML diagram at the very end of the document. Unfortunately I didn't find out how to embed a UML diagram anywhere in the documentation e.g. somewhere in the middle of a methods docstring block.
Does anyone know how to do that?
Adding the UML diagram directly in the docstring section didn't work for me.
But following worked for me:
Put plantuml code in separate file e.g. diagram.uml:
#startuml
Alice -> Bob: Hi!
Alice <- Bob: How are you?
#enduml
Add the plantuml directive with the filename at the desired place in the docstring. E.g.:
def example():
"""
some text
.. uml:: diagram.uml
some more text
"""
...
Related
I have a problem with C++ domain. In my index.rst I have
:cpp:func:`Hello()`
In hallo.rst I have the following lines:
.. cpp:function:: Hello
.. doxygenfunction:: Hello
The line with doxygenfunction works and I get the documentation generated for my function.
But the line with cpp:function doesn't work. Instead, I'm trying to generate a link for the Hello() function in the documentation.
I generated my C++ documentation with Sphinx, Doxygen and Breathe.
I don't know if I got your Question right. In the documentation of Breathe it is listed how to link a function.
doxygenfunction
This directive generates the appropriate output for a single function. The function name is required to be unique in the project.
.. doxygenfunction:: <function name>
:project: ...
:path: ...
:outline:
:no-link:
Check out: https://breathe.readthedocs.io/en/latest/directives.html#doxygenfunction
There is also an example page on how to link a single function: https://breathe.readthedocs.io/en/latest/function.html#function-example
It is possible to make work mermaid inside \.md file with MyST md driver ?
For now the only way I found is
$ tail conf.py
extensions = [ 'recommonmark', 'sphinxcontrib.mermaid']
from recommonmark.transform import AutoStructify
def setup(app):
app.add_transform(AutoStructify)
$
The below is rendered with recommonmark:
```mermaid::
graph LR
a --> b
```
but not with MyST-parser
I have open this issue in MyST: https://github.com/executablebooks/MyST-Parser/issues/366
Note: recommonmark does not render correctly tables that's why I try to use MyST-parser
mermaid is prefectly integrated to MyST-parser.
You only need to call it like that with {mermaid}:
```{mermaid}
graph LR
a --> b
```
No need to define in conf.py a def setup(app): only:
extensions = ['myst_parser', 'sphinxcontrib.mermaid']
In a reStructuredText on Sphinx 2.x, I want to put a content that changes depending on the output format.
In any source document, say, index.rst, add the following lines:
.. role:: pdf(raw)
:format: pdf
.. role:: latex(raw)
:format: latex
.. role:: html(raw)
:format: html
.. |foo| replace::
:pdf:`PDF!`
:latex:`LaTeX!`
:html:`HTML!`
I am |foo|
I expect it shows "I am HTML!" when the output format is in HTML, "I am LaTeX!" if it's LaTeX (even after converting the product to PDF via pdflatex) and "I am PDF!" if it's PDF.
I make the HTML version using make html and I see only "I am HTML!" in a web browser as I expect:
Install rst2pdf. Put the following lines in conf.py:
extensions = [
'rst2pdf.pdfbuilder'
]
pdf_documents = [(
'index',
u'testRst2Pdf',
u'Test Title',
u'Sarah Author')]
Make the PDF version with
sphinx-build -b pdf ./source/ ./build/
Update. Below is the output. No error. I ran this using WSL 1 (Ubuntu 18.04).
Running Sphinx v2.4.3
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [pdf]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing testRst2Pdf...
index
resolving references...
done
writing testRst2Pdf...
done
build succeeded.
I see "I am PDF! LaTeX! HTML!" that includes all the three items.
Is there any way to get either "I am PDF!" or "I am LaTeX!" in the PDF file?
Note.
Before reporting this behavior as a bug, someone help me check if it's unexpected behavior or as-designed.
This question is derived from the other I asked earlier: StackOverflow: "Sphinx: Use a different directive for a different output format".
rst2pdf does not really have conditionals, but you might find the --strip-elements-with-class switch useful? Put the optional pieces into a class name and then if that class doesn't make sense for this format, remove it with the switch.
Manual is here https://rst2pdf.org/static/manual.html#command-line-options and I also blogged (basically a longer version of this first paragraph) about this https://rst2pdf.org/static/manual.html#command-line-options if more information would be useful.
I'm trying to have a variable in conf.py that inserts a link that is applied on a string:
rst_epilog = """
.. |support| replace:: `support team <support#blabla.com>`_
"""
In this case 'support team' would turn into a link pointing to the email address.
Unfortunately, this does not work and the build breaks.
So I've tried dumping HTML in there, not knowing when the substitution happens, but it happens before HTML conversion, so that does not work in my output.
rst_epilog = """
.. |support| replace:: support team
"""
Any idea I could do this with a variable?
Use this substitution definition:
.. |support| replace:: support team support#blabla.com
support#blabla.com is automatically recognized as a mailto link.
The |support| substitution reference produces the following output:
support team <a class="reference external" href="mailto:support%40blabla.com">support<span>#</span>blabla<span>.</span>com</a>
An alternative is to use a raw-html role (see http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw).
Add this to conf.py:
rst_epilog = """
.. role:: raw-html(raw)
:format: html
.. |support| replace:: :raw-html:`support team`
"""
I'd like to be able to author footnotes at the point where they are referenced, but then only have them display at the end of the document, where .. rubric: Footnotes appears.
Like this:
Lorem Ipsum[#lorem]_ dolor sit blah blah.
.. [#lorem]
The footnote text here.
The next paragraph. Salve regina mater misericordiae, vita dulcedo.
.. rubric: Footnotes
DESIRED OUTPUT:
Lorem Ipsum^1 dolor sit blah blah.
The next paragraph. Salve regina mater misericordiae, vita dulcedo.
Footnotes:
1 The footnote text here.
According to the docutils docs this should be possible:
Footnotes may occur anywhere in the document, not only at the end.
Where and how they appear in the processed output depends on the
processing system.
But I can't find how to make the processing system (Sphinx, using the built-in make html) put them only at the bottom, instead of wherever they appear.
I've used the footnote approach, however, you must be careful about where you're placing the refs. So, my modules.rst look like this:
Brief
-----
.. automodule:: modules
:members:
:undoc-members:
:show-inheritance:
Sub modules
-----------
.. toctree::
:maxdepth: 4
modules.ahp
modules.grid
Plot module
-------------------
.. automodule:: modules.Plot
:members:
:undoc-members:
:show-inheritance:
Score module
-------------------
.. automodule:: modules.Score
:members:
:undoc-members:
:show-inheritance:
Skillset module
-------------------
.. automodule:: modules.Skillset
:members:
:undoc-members:
:show-inheritance:
util module
-------------------
.. automodule:: modules.util
:members:
:undoc-members:
:show-inheritance:
|hr|
.. rubric:: Footnotes
.. [#euclidian] `Wikipedia <https://en.wikipedia.org/wiki/Dot_product#Geometric_definition>`_
Since that my utils module contains the function where I'm using the footnote, it works like the expected. (It just creates a reference to a div in the current page)