I need to create one sphinx project for each module,
and each module share some common rsts, like company info, license, etc.
My project tree is like this:
./conf.py
./index.rst
./intro.rst
./about.rst
./device1/conf.py
./device1/index.rst
I write this in ./device1/index.rst, and it is not worked, how could I import parent rst files?
.. toctree::
:maxdepth: 1
../intro
../about
I found a way to do this:
.. include:: ../intro.rst
but it will include all the texts...
maybe it is the only way?
I personally couldn't figure out how to modify the source search path, so I ended up modifying the make file to create symlinks for all *.rst files in the sphinx build directory.
foreach f ( `\ls OTHER_DIR | egrep '.rst$$'` ) \
ln -s -f $$f BUILD_DIR \
end
(This presumes you're using Linux/Unix.)
Related
I have a Sphinx project that has the following structure:
projectRoot
|
|__mainDoc
| |__conf.py
| |__index.rst
|
|__subsections
|__subsectionA.rst
|__subsectionB.rst
In my conf.py, I have set my master_doc variable to "mainDoc/index", and to build the project I run the following command at the projectRoot directory: sphinx-build -c ./mainDoc -b singlehtml . _build
index.rst contains a simple toctree directive that lists the two subsection files like so:
.. toctree::
:numbered:
:hidden:
:maxdepth: 4
:caption: Contents:
../subsections/subsectionA
../subsections/subsectionB
subsectionA.rst:
.. _anchorA:
First Title
===========
This is a sample sentence.
subsectionB.rst:
Second Title
============
Please refer to :ref:`this sentence <anchorA>`
So far everything is pretty straightforward, and I was able to successfully build an HTML file. However, the cross-references are broken. Specifically, if the generated HTML file is in _build/maindoc/index.html, the link in subsectionB.rst points to _build/maindoc/maindoc/index.html#anchora, which is a file that doesn't exist since there's an extra maindoc folder in the path.
What is causing that extra folder to be inserted in the link target, and what can I do to fix that? Thanks in advance.
I am setting up a new project with multiple extensions. My goal is to track the code coverage for all extensions. Extensions live in subdirectories of the directory extensions and have multiple source folders. The number of extensions in my project is not final. So I will most certainly add one or more. Consider a structure like this:
extensions
extension A
src
testsrc
web
src
testsrc
extension B
...
All extensions follow the same structure. I am using the coverage-jdk11 job as described here:
https://docs.gitlab.com/ee/user/project/merge_requests/test_coverage_visualization.html#java-and-kotlin-examples
Now instead of
python /opt/cover2cover.py target/site/jacoco/jacoco.xml
src/main/java
> target/site/cobertura.xml
I need to add multiple src directories, which is supported. So my current version looks like this:
python /opt/cover2cover.py jacoco.xml
extensions/extensionA/src
extensions/extensionA/testsrc
extensions/extensionA/web/src
extensions/extensionA/web/testsrc
> cobertura.xml
But this one obviously only supports extensionA. My idea is to iterate through the subdirectories of the extensions directory and create multiple arguments for each subdirectory. But I have no idea how to do this in shell.
In the end I got it working with the following command:
find extensions -type d -maxdepth 3 -regex "^extensions/.*/\(testsrc\|src\)$" | xargs -t python /opt/cover2cover.py hybris/log/junit/jacoco.xml > hybris/log/junit/cobertura.xml
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.
The structure of my project that I want to document is as follows:
/top
Index.rst
/a
toctree_a.rst (contains doc and doc2)
doc.rst
doc2.rst
/b
toctree_b.rst (contains doc4 and doc3)
doc3.rst
doc4.rst
I want to reference the toctrees in the sub-directories (a and b) so that the project toctree can see the 4 documents in the project tree.
I know how do do this when the documents are in one directory, but I don't know how to do this if I have them in a subdirectory. I am trying to keep the structure of my project intact without having to move all files into one directory. I have done some research, and found that .. include:: directive may be the route to go, but I could not figure out how to use it properly.
you can tell your toctree in your index.rst to get the file from a sub-directory like so:
Contents:
.. toctree::
:maxdepth: 2
a/doc
a/doc2
b/doc3
b/doc4
That method works just like they would be in the same directory
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.