General-purpose, high-level programming language supporting multiple programming paradigms.
Sphinx is a tool for creating beautiful documentation for python projects. It uses reStructuredText as its markup language which it can build into various kinds of outputs. You can build HTML, PDF, manual pages and many others from one source! Sphinx can also link the documentation with your code and print syntax highlighted classes and functions. As extra, you can extend its functionality with many plugins and style it with many prepared themes.
To install Sphinx on Fedora:
For Python 2:
$ sudo dnf install python2-sphinx
For Python 3:
$ sudo dnf install python3-sphinx
Navigate your terminal into project directory and run:
to initialize your documentation. You will be asked to choose the documentation directory, set the project name and provide some other basic information about it. Next, you will be asked which extensions you want to enable. Be sure to answer “yes” on creating Makefile for your documentation.
It may happen that will miss-type some answer or you just change your mind about it. You can of course alter them whenever you want, just by editing
As it was mentioned before, content for Sphinx is written in reStructuredText, so in order to create new page in the documentation, you have to create a
.rst file. For example
Introduction ============ Here goes some introduction to your project and it is all written in rst format.
Now you have to open your master document, which is by default called
index.rst. It’s function is to serve welcome page and provide a table of contents for the documentation. Therefore you should add link to
.. toctree:: introduction
Sphinx can process your content to the various output formats. Run
make help to see all the possibilities. It should look like this:
Please use `make <target>' where <target> is one of html to make standalone HTML files dirhtml to make HTML files named index.html in directories singlehtml to make a single large HTML file pickle to make pickle files json to make JSON files ...
You will probably want to use
html for local testing purposes and
dirhtml for deploying. You are able to test it by hitting
make html to the command line. If Sphinx tells you that “Build finished. The HTML pages are in _build/html”, you have done it right and there is one last thing to do. Open the web browser in the current working directory (if you are not sure which one it is, just run
pwd to make sure), navigate to the build directory that Sphinx told you (i.e.
_build/html) and open
index.html. I would like to introduce you to your new documentation.