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?
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.
Is there a way to create a makefile that does this?
I gave up after trying to follow the docs and lots of trial and error so I'll just post a description of what the makefile should do.
general directory structure:
src/ - contains c source files in various subdirectories (written manually by maintainer)
inc/ - contains h header files in subdirectories matching src (written manually by maintainer)
obj/ - contains o header files in subdirectories matching src (autogenerated by a make call)
bin/ - should contain binary (autogenerated by a make call)
makefile
so for example at a given point of time the project might look like
src/
main.c
sub1/
other1.c
other2.c
sub2/
sub3/
other3.c
inc/
sub1/
other1.h
other2.h
sub2/
sub3/
other3.h
obj/
main.o
sub1/
other1.o
other2.o
sub2/
sub3/
other3.o
bin/
release
makefile
(probably not relevant: Note that main doesn't have a header file but most likely every other c file will have a matching h file.)
I want to be able to call make, and have it:
use gcc to recompile only changed c files into respective o files in obj/, generating missing subdirectories if needed.
for example, from the above state, if I add a new subdirectory sub4 inside src/sub1/, and then create other4.c inside src/sub1/sub4/, I would like make to generate sub4 inside obj/sub1/ and then generate other4.o inside obj/sub1/sub4/
create a binary at bin/release by linking all object files (from all subdirectories in obj/)
I don't want to have to change the makefile each time I add directories in src
I don't want to manually have to create directories in obj, the makefile should take care of it. if this is not possible, maybe have it rename all obj o files to a flat naming pattern? i.e. obj/sub2_sub3_other3.o instead of obj/sub2/sub3/other3.o (although this can cause issues)
probably not relevant here, but the C files use include statements in this format:
#include "sub2/sub3/other3.h"
so -I./inc would be included in the gcc call. Whereas the linker would receive inputs like -s -O3. I want to make sure those options (compiler options, linker options) are listed at the top of the makefile in variables (CFLAGS, LDFLAGS, etc) and not passed incorrectly to the targets.
is this even possible? if not, what's the closest possible?
Also, can this makefile be made to work on both POSIX systems and on Windows based systems? e.g. work the same on linux/gcc and win/mingw
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
Imagine a directory tree (which might be more than one level deep) containing several Markdown files. A PDF version of each file exist in the same directory and must be updated each time the corresponding Markdown file is updated. What rule must be written in a single Makefile in the root directory of this tree to achieve this?
I am looking a for a solution where files can be added or removed from the directory tree without a need for updating the Makefile.
Assumptions:
all markdown files follow a certain pattern in their name; for example they end with a .md postfix.
GNU Make is being used.
You can use $(shell find) to find files recursively. For example:
markdown := $(shell find . -name '*.md')
all: $(patsubst %.md, %.pdf, $(markdown))
%.pdf: %.md
pandoc -o $# $<