I am trying to use the include directive multiple times under a list-table directive. The following (a single include) works:
.. list-table::
:header-rows: 1
.. include:: path/to/file.rst
* - some text
- some more text
- another line of text
* - some text
- some more text
- another line of text
When I move the lists to external files and try to use multiple includes as such, it fails:
.. list-table::
:header-rows: 1
.. include:: path/to/file.rst
.. include:: path/to/file2.rst
.. include:: path/to/file3.rst
I get the following error:
WARNING: Error parsing content block for the "list-table" directive: exactly one bullet list expected.
How do I use multiple includes inside a list-table? I tried creating a bullet list with the includes but it doesn't work.
Related
I want to include full example scripts in Sphinx documentation. I originally simply duplicated an example file using a .. code:: directive, dropping in the entire python and json files for the example.
I then found the .. include:: directive, which lets to link to files by providing their relative path, and by using the code option, "The argument and the included content are passed to the code directive". This works fine for my python files, because the default decoding and highlighting for the code directive is python. But my json files are not highlighted as json. How do I indicate what code format the code directive should use to parse the code?
This is what I am using.
.. include:: ../../examples/my_example.json
:code:
I tried adding changing the second line to :code: json with no effect.
This is what I had originally, but want to replace so the example code does not have to be maintained in both the documentation and the examples.
.. code-block:: json
:name: my_example.json
:caption: my_example.json
{
"field1": "attribute1",
"field2": "attribute2",
"field3": true,
...
}
The solution is to instead use the literalinclude directive which has a language option. This is how it should look.
.. literalinclude:: ../../examples/my_example.json
:language: json
Note that literal include also supports options like linenos, lines, start-after, and end-before, caption, and name.
I need to include the following code in a .tex file that is generated from a custom template via RMarkdown, in order to get rid of an error. However, if I try it as below in the YAML heading:
header-includes:
\newenvironment{CSLReferences}%
{}%
{\par}
it gets parsed into the .tex file as single line, like \newenvironment{CSLReferences}% {}% {\par}, thus commenting out everything after %. So how can I change the YAML part so that it correctly gets interpreted as 3 different lines?
Instead of worrying about the markdown parsing, you can write the command in a single line:
header-includes:
\newenvironment{CSLReferences}{}{\par}
Alternatively avoid all these annoying problems with markdown parsing and put your definition in a .tex file which you can include via
includes:
in_header: header.tex
After some trials & searching this works (found a solution while writing the question):
header-includes:
- "\\newenvironment{CSLReferences}%"
- "{}%"
- "{\\par}"
Interestingly, I couldn't find much in the official documentation.
EDIT:
As #samcarter mentioned in the comments & an answer, in this particular case a single line would've been enough, as
header-includes:
\newenvironment{CSLReferences}{}{\par}
I wish to create an single_html.rst file that contains all my class/method/attribute/etc... , but also split categorised symbols into seperate pages.
e.g.
single_html.rst
.. single html
.. include:: foo.rst
.. include:: bar.rst
bar.rst
.. autoclass:: my.mod.Bar
:members:
foo.rst
.. autoclass:: my.mod.Foo
:members:
This throws multiple duplicate object description errors:
/path/to/project/my/mod.py:docstring of my.module.Bar:0: WARNING: duplicate object description of my.mod.Bar, other instance in /path/to/project/docs/source/api/single_html.rst, use :noindex: for one of them
/path/to/project/my/mod.py:docstring of my.module.Bar:0: WARNING: duplicate object description of my.mod.Foo, other instance in /path/to/project/docs/source/api/single_html.rst, use :noindex: for one of them
I can't simply place :noindex: on the autoclass:: directives as this will remove all the indexes completely. (so there are either duplicate indexes or none at all!)
Is there a better way to do this?
You can avoid those warnings by changing the extension of included files.
Sphinx considers each .rst (by default, it can be changed in the conf.py file) as a "source to parse" file. So it will try to parse the foo.rst and the bar.rst files and find autodoc directives for my.mod.Foo and my.mod.Bar.
When it tried to parse single_html.rst, it first include the content of foo.rst and bar.rst; thus, it then find again the directives for my.mod.Foo and my.mod.Bar.
By renaming foo.rst and bar.rst to foo.inc and bar.inc (of whatever you want as extension), you will prevent Sphinx from parsing the included files and will avoid the warnings.
I have just created my documentation using Sphinx and this is my problem:
Initially in the Toc tree directive is empty and then I add "tutorial" below and it looks like this:
.. toctree::
:maxdepth: 2
tutorial
and when I "make html", I do not get "tutorial" on the index page. Then I created a tutorial.rst in the same dircetory as index.rst. I do "make html"again and I get this error message:
toctree contains reference to nonexisting document
How do I fix this ?
Maybe try this :
.. toctree::
:maxdepth: 2
tutorial <tutorial>
..
Assuming your tutorial.rst file is in the "source" directory at the same level of your index.rst file
NOTE: newline is important between toctree options and page list.
You have to have an empty line between the maxdepth definition and the filename.
I'm getting the warning:
WARNING: document isn't included in any toctree
for files that exist in the document because they've been explicitly included. So I have the index file:
.. toctree::
:maxdepth: 2
pages/0010-foo
pages/0020-bar
In the file 0020-bar.rst, I'm specifically including a number of other files, as in:
.. contents:: :local:
.. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst
But when I build the project, I still get a warning that 0070-baz.rst isn't in any toctree, as in:
/home/nick/Documents/myProject/docs/pages/reference-architecture/technical-considerations/0070-baz.rst:: WARNING: document isn't included in any toctree
The weird thing is that I can see the content in the output. Is this normal? Does this warning always appear for files that are explicitly included rather than included via toctree?
If you only want to ..include:: a document in another document, without having it appear in any toctree.
Add :orphan: to the top of your document to get rid of the warning.
This is a File-wide metadata option. Read more from the Sphinx documentation.
Sphinx will complain about this whether the file is included or not.
However, you can specifically exclude files by using the exclude_patterns config value.
So for your case you might try to change Sphinx's conf.py file with something like:
exclude_patterns = ['pages/reference-architecture', 'some/other/file.txt']
You can exclude individual files, directories, or use file globbing patterns to match groups of files this way.
EDIT: See: Joakim's answer for another option that was added after this answer was created.
I had a situation where I couldn't edit the documents I wanted to be brought in as a git submodule. The documents already had their own structure including TOC page written in Markdown and I did want them to be processed by sphinx for consistency of formatting.
What I found I could do is specify a hidden toctree to make toctree aware of the documents, but not clutter up the toctree or add a bunch of errors to my sphinx build output.
* :doc:`Additional Book <external/index>`
.. toctree::
:hidden:
external/documentA.md
external/documentB.md
Indentation worked:
toctree::
:maxdepth: 2
hello <h.rst>
abc <your.rst>