sphinxnotes-fasthtml¶
Introduction¶
A Sphinx builder specialized for fast incremental HTML build.
The builtin StandaloneHTMLBuilder
supports
incremental build too, but it have to do a lot of extra work to ensure document
consistency (such as updating glob toctree, updating index, etc.) The fasthtml
builder skips almost all operations that slow down the build and left only
the necessary parts.
If you often need to edit and build Sphinx documents locally, and only want to preview the parts you modified, the fasthtml builder will be helpful to you.
Getting Started¶
Note
We assume you already have a Sphinx documentation, if not, see Getting Started with Sphinx.
First, downloading extension from PyPI:
$ pip install sphinxnotes-fasthtml
Then, add the extension name to extensions
configuration item in your
conf.py
:
extensions = [
# …
'sphinxnotes.fasthtml',
# …
]
Then you can run the fasthtml
builder:
$ sphinx-build -b fasthtml <sourcedir> <outputdir>
For Makefile users, it is recommended to add the following lines to your
Makefile, to share outputdir
betweens the fasthtml
builder and the
builtin html
builder:
# Without "make mode" we can specify OUTPUTDIR and DOCTREEDIR precisely
# so that we can make sure to share all output with the HTML builder.
fasthtml: Makefile
@$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) -d "$(BUILDDIR)/doctrees"
Then use make fasthtml
to run the fast HTML build.
Contents¶
The Sphinx Notes Project¶
The project is developed by Shengyu Zhang, as part of The Sphinx Notes Project.