Is it possible to have a default value for an include directive?
Let's say I have a line like this in my .adoc file:
include::{snippets}/some-snippet.adoc[]
in case if the file {snippets}/some-snippet.adoc is not present, I want a default value to be displayed instead. Something like this comes to mind:
include::{snippets}/some-snippet.adoc[default='a snippet of something']
but I cannot find anything like it in the docs.
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 use sphinx to generate HTML and PDF documentation, and was using latex until now to generate PDF, but now looking at swapping for rinohtype.
I'm looking at setting up some custom headers and footers, but would like to include variable text into them, for the version number for example, which comes from a sphinx python plugin. I have rst substitutions, for example |version|, that I use in various places in the document, but if I add it to the header via a stylesheet it doesn't get substituted. I also have python variables, for example version, in my conf.py so I also tried to use {version} in my stylesheet, but the builder complains that the variable doesn't exists.
FYI, here is how I tried to define my header :
[contents_page]
header_text = '|document_id| |version| |shortdate|' (header)
[contents_page]
header_text = '{document_id} {version} {shortdate}' (header)
Any idea how to get around that issue ?
Thanks
rinohtype does support including reStructuredText substitutions (|subst|) in document templates, but this is one of the features that isn't documented yet.
To use substitutions in a page header or footer, you need to include them as follows:
[contents_page]
header_text = '{UserStrings.document_id} {UserStrings.version} {UserStrings.shortdate}' (header)
(Actually, I don't remember why I require the UserStrings. prefix. Perhaps there is a good reason for that. If not, that prefix might not be needed in the future.)
Context
I am making a script that dynamically inserts include directives in code blocks on an AsciiDoc file and then generates a PDF out of that. A generated AsciiDoc file could look like this:
= Title
[source,java]
---
include::foo.java[]
---
I want the user to be free to include whatever char-based file he or she wants, even other AsciiDoc files.
Problems
My goal is to show the contents as are of these included files. I run into problems when the included file:
is recognized as AsciiDoc beacuse of its extension, an thus any include directives it has are interpreted. I don't want nested includes, just to show the include directive in the code block. Example of undesired behaviour:
contains the code block delimiter ----, as seen on the image above when I end up with two code blocks instead of the intended single one. In this case, it does not matter if the file is recognized as an AsciiDoc file, the problem persists.
My workaround
The script I am writing uses AsciidoctorJ and I am leveraging that I can control how the content of each file is included by using an include processor. Using the include processor I wrap each line of each file with the pass:[] macro. Additionally, I activate macro substitution on the desired code block. A demonstration of this idea is shown in the image above.
Is there a better way to show the exact contents of a file? This works, but it seems like a hack. I would much rather prefer not having to change the read lines as I am currently doing.
EDIT for futher information
I would like to:
not have to escape the block delimiter. I am not exclusively referring to ----, but whatever the delimiter happens to be. For example, the answer by cirrus still has the problem when a line of the included file has .....
not have to escape the include directives in files recognized as AsciiDoc.
In a general note, I don't want to escape (or modify in any way) any lines.
Problem I found with my workaround:
If the last char of a line is a backslash (\), it escapes the closing bracket of the pass:[] macro.
You can try using a literal block. Based on your above example:
a.adoc:
= Title
....
include::c.adoc[]
....
If you use include:: in c.adoc, asciidoctor will still try to find and include the file. As such you will need to replace include:: with \include::
c.adoc:
\include::foo.txt[]
----
----
Which should output the following pdf:
In our read the docs project we have a use case where we need to show some specific docs on multiple pages in the same version of docs. As of now, we do this either by one of the following ways
Copy-pasting the content to each page's rst file
Write it in one of the concerned files with a label and use :std:ref: in rest of the files to redirect it to the main file
I would want to achieve something like writing content only in one file and then showing it (without any redirection for user) in each of the files. Is it possible?
Use the include directive in the parent file.
.. include:: includeme.rst
Note that the included file will be interpreted in the context of the parent file. Therefore section levels (headings) in the included file must be consistent with the parent file, and labels in the included file might generate duplicate warnings.
You can use for this purpose the include directive.
Say that you write the text in dir/text.rst.
The following will include in other documents:
..include :: /dir/text.rst
where the path is either relative (then, with no slash) or absolute which is possible in sphinx (doc)
in Sphinx, when given an absolute include file path, this directive
takes it as relative to the source directory
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?