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.
Related
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.
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.
How can I get my Sphinx RST file to include a link to the "contents.html" Python help page?
More Details
I have an RST help document (index.rst) in an offline environment. I have downloaded and successfully built the Python documentation using the command make.bat html. I then copied this documentation to C:\Temp\PyDoc.
I then updated my conf.py file to include the following Intersphinx mapping:
intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}
Then, within my index.rst file, I have something like:
Contents:
.. toctree::
:maxdepth: 1
:ref:`Python <python:contents>`
The Python link is removed from the resulting documentation with the warning message:
WARNING: toctree contains reference to nonexisting document ':ref:`Python <python:contents>`'
I have verified that the output contains the text:
loading intersphinx inventory from C:/Temp/PyDoc/objects.inv...
I have also verified that the "contents" tag exists within the Python documentation by running:
python -m sphinx.ext.intersphinx "C:/Temp/PyDoc/objects.inv" | findstr contents
Which generates output that includes the line:
contents Python Documentation contents : contents.html
Does anyone know how to reference this external documentation from my RST file?
In the configuration for intersphinx, the dict's key's value is a tuple, which consists of comma-separated values, not colon-separated.
intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}
EDIT
toctree entries need a valid target, which can be a file relative to the current file or absolute as starting from the documentation root where your conf.py resides. Also the target may be an URL. I suspect that the HTML you made is none of the above, so you need to move it to a place where Sphinx can find it.
The syntax should be for documentation, not a Python object, because the page is a table of contents. I did not try this example because I don't have the Python docs downloaded and built, so I doubt it will work.
.. toctree::
:maxdepth: 1
:doc:`Python <python:contents>`
Or you can just use the URL (or similar relative or absolute target). This works for me with a fully qualified URL.
.. toctree::
:maxdepth: 1
Python <https://docs.python.org/3/contents.html>
Finally you could try an include, but I think that is not what you really want.
I am trying to write documentation and want and have multiply files used by multiple toc trees. Previously I used an empty file with .. include:: <isonum.txt> however, this does not work for multiply files in a directory with sub directories. Another solution I have used was to use a relative file path to the index file I am linking to. However this messes up the sphinx nav tree. So my question is how to include a directory of files with RST and Sphinx?
It can't be done, unfortunately.
The toctree directive has a glob option, which you would use like so:
.. toctree::
:glob:
generated/*
But this option is not available in the include directive.
Maybe start an issue for it?
Perhaps indicate the start and end of the section where the files should go with a comment (.. START_GLOB_INCLUDE etc), and then have a build pre-process step that finds the files you want and rewrites that section of the master file.
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>