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.
As reported here: https://github.com/rtfd/readthedocs.org/issues/3411 sphinx sometimes fails with the error:
```python
File "/home/docs/checkouts/readthedocs.org/user_builds/drf-yasg/envs/latest/lib/python3.5/site-packages/sphinx/ext/viewcode.py", line 74, in has_tag
if entry is None or entry[0] != code:
TypeError: 'bool' object is not subscriptable
```
This is not critical as whipping the build or even just running it again fixes it, but the error is confusing...
I believe switching the two if statement above should prevent this from happening.
Read the Docs moved hosting to readthedocs.io instead of
readthedocs.org. Fix all links in the project.
For additional details, see:
https://blog.readthedocs.com/securing-subdomains/
> Starting today, Read the Docs will start hosting projects from subdomains on
> the domain readthedocs.io, instead of on readthedocs.org. This change
> addresses some security concerns around site cookies while hosting user
> generated data on the same domain as our dashboard.
