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?
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.
I am writing lots of Sphinx/RestructuredText and this includes Sequence Diagrams using PlantUML. I have lots of text that I am reusing, so to make things cleaner, I created a definitions.iuml file. In this file, I can create named text references (via !startsub/!endsub blocks) that allows me to reference them in several different Sequence Diagrams. Change it once in the source location, and they all change. Perfect.
My problem is how to use these references outside of Sequence Diagrams? I use the exact same code (!includesub ../defintions.iuml!NAMED-REFERENCE) in the .rst file, and when I make docx/pdf, I see that link, I don't see the text that it is referencing. To make things worse, Google has like no documentation or search results on this. Queries of includesub, startsub, endsub +sphinx come back with nothing.
Help me obiwan kenobi.
I found the answer, which only resulted in more questions haha. Anyway, one thing at a time:
To create reference variables in your text document, use rst_prolog or rst_epilog in your Conf.py file. Why there are 2 commands that serve the same purpose, I dont know.
rst_prolog = """
.. |Variable1| replace:: Monday
.. |Variable2| replace:: Tuesday
"""
Now whenever you write |Variable1| in your text, the document will generate Monday.
The problem with the above is that its just for short words/phrases. You can't use it for code blocks, or anything that is more than one line. To reference in Code Blocks:
Create a new .rst file with the code you want to display. Best practice is to create a Code folder and place them all in there.
Further best practice is to stop using the '.. code block::' and instead use '.. parsed-literal::'. The output is the exact same, but parsed-literal allows you to use conf.py variables and ..codeblock:: doesn't.
So in this .rst file, first line is .. parsed-literal:: and all the text below it is the code you want to reference
In the original document that you wanted this code, type:
<4 spaces indent>.. include:: <Folder/File.rst>
Generate your document, and notice how the code is now being reference. You can include this reference all throughout your document.
I will soon be creating a new thread, this time asking how the text body and sequence diagrams can use the same reference. Currently, all text needs one reference, all sequences need another reference, and now we have double updates. Not ideal
In markdown I can write:
[example1][myid]
[example2][myid]
[myid]: http://example.com
so I don't have to retype the full external link multiple times.
Is there an analogous feature in AsciiDoc? Specially interested in the Asciidoctor implementation.
So far I could only find:
internal cross references with <<>>
I think I saw a replacement feature of type :myid:, but I can't find it anymore. And I didn't see how to use different texts for each link however.
Probably you mean something like this:
Userguide Chapter 28.1. Setting configuration entries
...
Attribute entries promote clarity and eliminate repetition
URLs and file names in AsciiDoc3 macros are often quite long — they break paragraph flow and readability suffers. The problem is compounded by redundancy if the same name is used repeatedly. Attribute entries can be used to make your documents easier to read and write, here are some examples:
:1: http://freshmeat.net/projects/asciidoc3/
:homepage: http://asciidoc3.org[AsciiDoc3 home page]
:new: image:./images/smallnew.png[]
:footnote1: footnote:[A meaningless latin term]
Using previously defined attributes: See the {1}[Freshmeat summary]
or the {homepage} for something new {new}. Lorem ispum {footnote1}.
...
BTW, there is a 100% Python3 port available now: https://asciidoc3.org
I think you are looking for this (and both will work just fine),
https://www.google.com[Google]
or
link: https://google.com[Google]
Reference:
Ascii Doc User Manual Link
Update #1: Use of link along with variables in asciidoc
Declare variable
:url: https://www.google.com
Use variable feature using format mentioned above
Using ' Link with label '
{url}[Google]
Using a relative link
link:{url}[Google]
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.