CODEWITHSUNDEEP
pythonmakefilepython-sphinxexclusionpath
showkey
showkey

Reputation: 348

How can I generate rst file in parts of directory into HTML file in Sphinx?

Display my Sphinx project's directory structure.

cd myproject/source
tree -d
.
├── django
├── document
├── excel
├── github
├── _images
├── _templates
└── vim

Everytime I execute the command make html, all the *.rst files in django, document, excel, github, vim will be generated into *.html. Now I want to only generate parts of *.rst file into *.html, say, I want to keep all the *.rst files in github and vim un-maked, how to execute the make html command?

Upvotes: 1

Views: 1150

Answers (1)

bad_coder
bad_coder

Reputation: 12870

Notice by looking inside the make file it's just a generated batch or shell script (depending on OS) that calls sphinx-build for you setting the arguments to default values.

set SPHINXBUILD=sphinx-build
set BUILDDIR=build
set SOURCEDIR=source

(...)

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

Equivalent to the signature from the documentation:

sphinx-build [options] <sourcedir> <outputdir> [filenames …]

say, I want to keep all the *.rst file in github and vim un-maked

The easiest way to achieve what you want, is excluding the directories you don't want to build:

sphinx-build -b html ./source ./build -D exclude-patterns=github/*,vim/*

The -D setting=value option is equivalent to passing the exclude-patterns=[] normally found in your conf.py through the command line.

how to execute the make html command?

If you want to use the make file you can also pass the above arguments to make html using SPHINXOPTS. Some users got it to work, however I haven't been able to on Windows.

A more complicated option, that may be necessary depending how you want to layout your documentation, would be to have an individual Sphinx project for every source directory, with its own make.bat, conf.py and index.rst. If you have a single index.rst that by default links to .rst files in the excluded directories, you may have to conditionally exclude parts of index.rst.

Notice the -c and -C options.

Upvotes: 1

Related Questions