Friday, December 26, 2014

sphinx-doc failing for manpage builder

Sphinx-doc (http://sphinx-doc.org/latest/index.html) is a utility to create intelligent and friendly documentation with existing support for Python and C/C++ projects.

It can produce documentation in varied formats like html, LaTeX, epub, Texinfo, manpages and plaintext. It has lots of other features and multiple community created extensions to hyper-activate its usability.

To give it a quick try "Sphinx - First Steps" tutorial can be used, or a bit more with "sampledoc tutorial".

Here we will be discussing issue faced whilst creating manpages from a sphinx-documented project raising issue for "man" builder not being supported.

The solution is very simple but being a beginner (or external user) makes one doubt it.

System package version of Sphinx-doc for some of the distros is still not above v1.0 and the manpage support is just found in those.
So, to counter this error just don't use system package for it but instead use "pip install sphinx".

If you don't have pip already, follow this article: https://pip.pypa.io/en/latest/installing.html .