Ceci est une ancienne révision du document !
Sphinx is a very nice document processor; it can create html, latex, pdf’s, and more. I started using it a few years ago to write a short book about Wood Turning. The reason for choosing Sphinx is its ability to create the different styles by creating only a config file and writing the document in reStructuredText. Here is the documentation: http://docutils.sourceforge.net/rst.html
If you have not used markup, you are missing out. Try it out. All you need it an editor such as vim/gvim or ??? – your choice – do not use a word processor. So here is the basic layout for the markup and how to install Sphinx (by the way, Sphinx was written to create Python documentation).
This was copied from the Sphinx documentation page: http://www.sphinx-doc.org/en/stable/ • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text • Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information • Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children • Automatic indices: general index as well as a language-specific module indices • Code handling: automatic highlighting using the Pygments highlighter • Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and • Contributed extensions: more than 50 extensions contributed by users in a second repository; most of them installable from PyPI
OK, let’s install Python and Sphinx; most distributions come with Python installed or at least in the package manager. You may still need to install PyPi to use pip:
sudo apt install python-pip
Install Sphinx, either from a distribution package or from PyPi
$ pip install Sphinx
or
sudo apt install python-sphinx
this works best for Ubuntu 16.04.01
Then run and answer all questions, be sure to say yes to autodoc extensions. If you want to create a directory first and change to that dir, quickstart will do it for you:
$ sphinx-quickstart
After this is finished, you will have a index.rst file that looks like this, and you will have a conf.py file created from the questions you answered in the quickstart.
:maxdepth: 2
intro
tutorial
Just add your chapters etc into this file as shown in the example at the bottom of the previous page.
You may want to look through the conf.py file and see if it is what you want, if not make the changes. Then type:
make html
This will build the documentation you just created in html format under the _build/html directory. If you make for other types of files, you will see the directories created in the _build dir. Example:
doctrees html latex tex xml
I hope this is of use to some people who like to try new ways of using Ubuntu/Linux.