It is useful to have the HTML documentation builder actually link to
real rendered versions of HTML manpages in its output. That way people
can click on manpages to get the full documentation. There are a few
services offering this online, so we do not explicitly enable one by
default, but the Debian manpages repository has a lot of the manpages
pre-rendered, so it is used as an example in the documentation.
The parsing work is done by a transformer class that parses manpage
objects and extract name/section elements. Those then can be used by
writers to cross-reference to actual sites. An implementation is done
in the two HTML writers, but could also apply to ePUB/PDF writers as
well in the future.
This is not enabled by default: the `manpages_url` configuration item
needs to be enabled to point to the chosen site. The `page`, `section`
and `path` parameters are expanded through Python string formatting in
the URL on output.
Unit tests are fairly limited, but should cover most common use-cases.
closes#4142closes#4357closes#4359
refs: #3967
Adds ``smartquotes``, ``smartquotes_action``, ``smartquotes_excludes``
configuration variables.
- if ``smartquotes`` is set to False, then Smart Quotes transform is not
applied even if a Docutils configuration file activates it,
- the current default of ``smartquotes_excludes`` deactivates Smart
Quotes for Japanese language, and also for the ``man`` and ``text``
builders.
However, currently ``make text html`` deactivates Smart Quotes for
``html`` too, and ``make html text`` activates them for ``text`` too,
because the picked environment is shared and already transformed.
- now Smart Quotes get applied also when source documents are in
Markdown or other formats.
Notes:
- also fixes#4314
- although numbering of figures, tables and code-blocks will be same as
in html, due to issue #4318 the numbering of enclosing sectioning units
themselves may go deeper in html than PDF via latex. But this commit
makes sure numbering goes to minimal depth needed by numfig_secnum_depth
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.
