In my conf.py I have defined the master as index ( index.rst)
# The master toctree document.
master_doc = 'index'
When I import a list of rst files using the .. include:: list.rst where list .rst file is being created dynamically.
Project Test
================================
.. include:: list.rst
it works fine; but when I add some other rst names in the same index.rst it doesn't work, like static.rst and about.rst in the following declaration :
Project Test
================================
.. include:: list.rst
static
about
I created a new file staticList.rst and moved all the static rst names.
.. toctree::
:maxdepth: 1
static
about
and included the staticList.rst in the index.rst file, it is giving the desired result but slightly broken listing.
Project Test
================================
.. include:: list.rst
.. include:: staticList.rst
Related
Let's say I have this structure in my source folder for my sphinx documentation :
journals /
*.md files
reports /
*.html files
conf.py
index.rst
and the following code in index.rst :
.. toctree::
:maxdepth: 4
:glob:
:caption: Reports
reports/*
.. toctree::
:maxdepth: 4
:glob:
:caption: Journals
journals/*
When I generate my docs with sphinx-build, sphinx automatically builds the resulting html pages with the .md files found in my journals folder, but it ignores the .html files found in the reports folder.
What I would like is for sphinx to automatically include the .html files found in the reports folder. The resulting .html pages should still include the sphinx layout (sidebar, headers, etc.), and should not just be a pure copy of the raw .html files.
I know I could do .rst files with the following :
.. raw:: html
:file: reports/file.html
This basically does what I want. The .rst file is found by sphinx and builds a .html file that includes both sphinx layout and my source .html file.
I just don't know how to do this automatically though, as I have a lot of files in my reports file. I would prefer to avoid having to create one .rst file for each of my .html file.
Is there a way to automatize this process with sphinx-build?
I've got something like this:
.. toctree::
:maxdepth: 2
:caption: Contents:
:hidden:
:glob:
docs
frontend
backend
tools/*
I'd like all the documents found in the tools directory to collapse into one expandable sidebar TOC entry. Should be possible, but I can't find a clue.
I use sphinx_rtd_theme.
To put it another way: suppose I have a very long document like this (tools.rst):
Section 1
*********
Subsection 1
============
Subsection 2
============
Subsection 3
============
How am I supposed to split it by the subsection and preserve the document structure, without resorting to includes, which don't sit well with Sphinx anyway.
source/index.rst:
.. toctree::
:maxdepth: 2
:caption: Contents:
:glob:
tools/_tools
docs
frontend
backend
tmp/*
Old source/tools/_tools.rst:
Notes on tools
**************
.. include:: black.rst
.. include:: docker.rst
.. include:: git_hooks.rst
.. include:: github_webhooks.rst
.. include:: mypy.rst
.. include:: pipm.rst
.. include:: poetry.rst
.. include:: sphinx.rst
.. include:: uvicorn.rst
New source/tools/_tools.rst:
Notes on tools
**************
.. toctree::
:maxdepth: 2
:glob:
*
The new one renders exactly like the old one, and is more versatile an a lot cleaner.
I seek to make an "API Reference" page exposing genindex.html and py-modindex.html; problem is, I rather the entire page not be just clickable links to said pages, but to actually include their contents. We can do this with a README - however, README.rst exists in source/, whereas genindex.html is only in build/, so below don't work:
.. include:: modindex
.. include:: genindex
.. include:: modindex.rst
.. include:: genindex.rst
.. include:: ../build/genindex.html
Can this be accomplished?
I have a file called version.h that among other things contains the following line:
#define VERSION 0.4.2-b
Now, on the Sphinx documentation for this piece of software, I'd like to display this value in one of the .rst files.
How can I do this?
Thanks!
See the literalinclude directive.
In your case:
.. literalinclude:: version.h
:language: c
For the proper syntax highlighting, you can change the Pygments lexer by specifying the language attribute.
this is my project tree structure:
srcdir/Makefile_parent.make
srcdir/src/Makefile_src.make
srcdir/data/Makefile_data.make
srcdir/other/Makefile_other.make
My question is how to pass from my "Makefile_parent.make" a value readable in the child makefiles..I have:
Makefile_parent.make
ParentData = foo
SUBDIRS = src data other
and later, I want to read it from the other makefiles, for example:
Makefile_src.make
GetParentData = $(ParentData)
But is not working is always empty..any ideas?
In your Makefile_src.make, you need to add this line at the top of the file:
include Makefile_parent.make
Then there is a problem of including the same makefile multiple times. A solution for that (similar to #ifndef in header files ;) )
ifndef MAKEFILE_PARENT_MAKE
MAKEFILE_PARENT_MAKE := 1
...
...
...
...
endif
You need to do this for every makefile you think that might be included, and use a different variable name for each of those files.