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.
Related
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 have a C++ project that I'm documenting with Sphinx. To keep the source directory clean, it uses an out-of-source build. I have a tutorial program that gets built as part of the project and generates an image in the build directory, not the project source directory. How can I reference the image in documentation files in the source directory when I have no control over the relative location of the source and build directories of the project?
I've tried using an rst_epilog in conf.py like so:
rst_epilog = """
.. |builddir| replace:: %s
""" % project_build_dir
and then refer to the image like so:
.. figure:: |builddir|/generated.png
but end up with errors like "WARNING: image file not readable: |builddir|/generated.png".
It looks like this is answered in the negative by this question: reStructured Text (Sphinx) : substitution in a file name? . Substitutions cannot be used in image directives to modify the filename and no alternative was offered other than to write a new extension or manually generate an image substitution for every image.
I have a directory which internal contains sub directories. I want to include the parent directory as include path in make file for header files. Is there a syntax so that all the sub directories are searched for the header files.
[EDIT] Posting the question in more detail
There are three sub folders in a parent folder
parentFolder/child1
parentFolder/child2
parentFolder/child3
There are header files in each all subfolders
Using -I option in makefile for header file path, i have to use
HEADER_PATH += -I./parentFolder
HEADER_PATH += -I./parentFolder/child1
HEADER_PATH += -I./parentFolder/child2
HEADER_PATH += -I./parentFolder/child3
Is there any way I can mention only the parent folder , but the search for header files will happen in all the subfolders also
http://www.gnu.org/software/make/manual/html_node/Recursion.html
Setup variable in first makefile and export it for sub-dirs. If you want to be able to invoke make in subdirs manually - i suppose best way to achieve this is either using configure-like systems to generate paths for you, or setting global variable (e.g. YOURPROJECT_DIR) in .profile or .bashrc and using it in makefiles.
I would like to see better solutions since i've encountered quite the same problem some time ago.
I have a lot of Sphinx pages which have the same links on them. Like those:
.. _CC-BY: https://creativecommons.org/licenses/by/3.0/
.. _MIT: http://opensource.org/licenses/MIT
Currently, I have those two lines in every file that has a MIT_ in it. Is it possible to have a central file in the project where I can put those link targets? That way, I could write MIT_ anywhere and it would link to that.
Put your link definitions in rst_epilog in conf.py:
rst_epilog = """
.. _CC-BY: https://creativecommons.org/licenses/by/3.0/
.. _MIT: http://opensource.org/licenses/MIT
"""
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>