In Python 3, the default encoding of source files is utf-8. The encoding
cookie is now unnecessary and redundant so remove it. For more details,
see the docs:
https://docs.python.org/3/howto/unicode.html#the-string-type
> The default encoding for Python source code is UTF-8, so you can
> simply include a Unicode character in a string literal ...
Includes a fix for the flake8 header checks to stop expecting an
encoding cookie.
It was introduced to fake its type information and make mypy silent.
But the warnings had came from wrong typing of docutils-stubs.
(see https://github.com/tk0miya/docutils-stubs/pull/28)
After the fix, the helper method is not needed for us. So this
removes it right away.
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.
Instead rely on docutils’ ‘smart_quotes’ option which is available
since docutils 0.10.
This adds support for internationalization: our code supported only
English quotes, while docutils code supports 27 different languages.
Closes#498, #580, #3345, #3472.
