While hanging around IRC in both #sphinx-doc and #readthedocs
I have found that a lot of people do not know about these options
even though a lot of theme are pretty common. For example,
adding a simple theme overide, most people will edit layout.html
instead of Sphinx.add_stylesheet.
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.
* Adds nesting to the JavaScript domain, to allow for nesting of elements
* Adds the ``js:module`` directive, which behaves similarly to the Python
directive
* Adds the ``js:method`` directive, an alias to ``js:function``
* Adds roles for ``js:mod`` and ``js:meth``
* Updates tests to passing cases
* Adds docs for new features
- allow multi-paragraph contents in grid table merged cells
- allow code-blocks in merged cells
- allow generally speaking reST contents allowed in regular
cells to be also allowed in merged cells, whether multirow,
multicolumn, or both.
This is made possible by custom LaTeX macros replacing original
``\multicolumn`` and ``\multirow`` (none of the originals allows
verbatim contents as is needed for code-blocks). They are defined in
bundled LaTeX style file sphinxmulticell.sty. The multicolumn merged
cells give much better results with tabulary as it is coerced into
taking them into account in its automatic width algorithm.
This deprecates use of LaTeX packages eqparbox and multirow, which are
not needed anymore.
New config setting ``latex_use_latex_multicolumn`` (default value False,
currently) as custom Sphinx multicolumn is not fully compatible will all
types of custom table col specs which may be inserted via tabularcolumns
directive. It works best with standard ``|`` column separator.
The default tabulary column specifier has been changed from L
(flushleft) to J (justifying). Internally the column type is called T,
so ``r'\newcolumntype{T}{L}'`` in preamble key recovers the former
behaviour. A ``\Y`` column type is defined which admits one decimal
argument in place of the two integers for ``\X``.
At present, the 'builder' option for the setuptools integration only
supports a single output format, typically HTML, like so:
[build_sphinx]
builder = man
There is value in being able to specify multiple format, like so:
[build_sphinx]
builder = html man
Make this possible.
Signed-off-by: Stephen Finucane <stephen@that.guru>
While this feature is somewhat documented in the API guide, there's
nothing about this option in the main user guide. Given the lack of
blogs and articles talking about this feature, along with the amount of
projects that are only using the same copy-paste '[build_sphinx]'
definition, I imagine this is an issue.
Make the feature a little more accessible by adding a section to the
main user guide that details (a) the fact the feature exists, (b) why
you'd want to use it, and (c) how you can use it.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This reverts commit 839e924808.
Indeed, it is better not to document how to use ``lines`` with
``start-after`` now if this is to be changed at next major release (refs
indeed, customization will generally go via the `̀ 'sphinxsetup'`` keys
for margins or can be achieved via use of ``'passoptionstopackages'``.
Thus the key primary use would now be to remove entirely use of
``geometry`` package, which should be rarely needed.
- make text width integer multiple of zenkaku width
- fix incompatibility of ``geometry`` package with ``jsbook`` LaTeX
class (``'manual'`` docclass)
- fix issue with shortened text area height in ``'manual'`` docclass
--
Move `parents`, `prev` & `next` to
*documents that are created from source files* section.
It doesnt make any sens to use them for auto-generated files like index and
search, does it?
Add documentation for `body`, `display_toc`, `metatags` and `title`.
Sphinx's `make gettext` always creates the .pot files in
$BUILD_DIR/gettext, regardless of the paths configured in `locale_dirs`;
those only affect sphinx-intl's operation
