The trick is to create an Index TOC/bookmarks entry in anticipation of
makeindex execution, as RTD (currently) does only one pdflatex run after
makeindex.
https://github.com/rtfd/readthedocs.org/issues/2857
The workaround works for Sphinx own docs, which uses ``'manual'``
docclass and puts the general index at very end of document.
This is tested to work with latexmk version: 4.39 (10 Nov 2013).
For xelatex engine and with latexmk 4.52b or later (Jan 2017), setting
LATEXMKOPTS Makefile variable on command line to "-xelatex" results in
faster builds, because PDF is produced only on last run.
For example, if a graphics file is missing. The error is still reported
but some functional PDF may still have been produced. Some projects have
temporary errors with LaTeX (missing Unicode characters, graphics file
using wrong formats, ...) affecting some small percentage of the
documentation, and it may be important to make at least some PDF
available, postponing complete resolution of LaTeX problems to a later
date.
The autodoc_mock_imports option requires to explicitly declare *every*
external module and sub-module that are imported by the documented code.
This is not practical as the list can become very large and must be
maintained as the code changes.
Also, the mocking is minimal which causes errors when compiling the
docs. For example, if you declare:
autodoc_mock_imports = ['django.template']
And try to document a module:
.. automodule:: my.lib.util
Which contains this code:
from django.template import Library
register = Library()
The following error occurs:
File ".../my/lib/util.py" line 2
register = Library()
TypeError: 'object' object is not callable
Other similar errors can occur such as "TypeError: 'object' object has
no len".
To address these limitations, only require to declare the top-level
module that should be mocked:
autodoc_mock_imports = ['django']
Will mock "django" but also any sub-module: "django.template",
"django.contrib", etc.
Also, make the mocked modules yield more complete dummy objects to avoid
these TypeError problems.
Behind the scenes, it uses the python import hooks mechanism specified
in PEP 302.
Signed-off-by: Robin Jarry <robin@jarry.cc>
Thanks to tk0miya's comment, I learnt one can add stuff to template
blocks, that allows a much simpler stylesheet configuration, considering
that changes at the template level will be more... well, low-level.
Hopefully this is now acceptable.
A builder is uniquely identified by its name, which can be used as an
entry point in the 'sphinx.builders' entry point group. This obviates
the need to register the builder as an extension.
The built-in builders are still loaded as before. New third-party builders
should provide an entry point in their setup.py:
entry_points={
'sphinx.builders': [
'mybuilder = mypackage.mymodule:MyBuilder',
],
}
Like before, builders should define a setup(app) function in the
'mypackage.module' module to define configuration variables etc. It is
no longer necessary to register the builder using Sphinx.add_builder().
Existing builders can still be loaded the traditional way, by including
their module name in the extensions list in conf.py.
