0x01 Sphinx

Sphinx is a huge and enormous stone like a mixture of lion and people ,where is located at Egypt. However I will introduce a tool that makes it easy to create beautiful and intelligent documentation,written by Georg Brandl and licensed under the BSD license.
The following features should be highlighted:

  1. Output formats:HTML, LaTex, ePub, Texinfo, manual pages, plain text
  2. Extensive cross-references:semantic markup and automatic links for functions, classes, citations, glossayr terms and similar pieses of information
  3. Hierarchical structure:easy definition of document tree(toctree)
  4. Automatic indices:general index as well as language-specific module indices(not understande)
  5. Code handling:automatic highlighting using the Pygments highlighter
  6. Extensions:automatic testing of code snippets
  7. Contributed Extensions:more than 50 extensions contributed by users

0x02 First Steps with Sphinx

  1. Install Sphinix

    1
    $pip install Sphinx

  2. Setting up the documentation sources
    The root directory of a Sphinx collection of reStructuredText document sources is called source directory.
    Sphinx comes with a script called sphinx-quickstart that sets up a source directory and create a default conf.py with the most useful configurations values from a few questions it ask you.

  3. Add you modules into index.rst
    After you run sphinx-quickstart,you could add the module of you source into the toctree(table of contents tree)

  4. Make HTML
    You can run the directive make html created by the script sphinx-quickstart. Then you will get your documentation of you project.

  5. Shpinx-apidoc
    Sphinx-apidoc is great tool esides sphinx-quickstart.It can creat rst file of your project conveniently. More information

0x03 Suggetions

According to my experience I prefer to use Google Python Style Guide.
Like this

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
#! /usr/bin/env python

"""This is file docstrings test

"""
class ObjectA(object):
  """This is a test class for sphinx.

    Note:
      this is class level docstring.

    Args:
      para1 (str): Description of `param`
      num (int): Description of param num
  """

  def __init__(self, para1, num=0):
    self.para1 = para1
    self.num = num

  def example_method(self, para1, para2):
    """Class methods introducation
    
    Args:
      para1 (str): The firest parameter
      para2 (str): The seconde parameter

    Returns:
      True if successful,False otherwise.
    """
    return True

Using this way you can use the extension napoleon to create more readable code style instead of reStructuredText documentation.
Be careful you should set configuration value extensions add sphinx.ext.napolean. More information about napolean
The last you need add the path of your project into the sys.path for sphinx searching your code. So you need to add the “sys.path.insert(0, os.path.abspath(‘YOU PYTHON SOURCE PATH’))” into the conf.py .

0x04 Summary

All in all,that’s my way to creat beautiful documentation:

  1. write beautiful code
  2. sphinx-apidoc -F -o outdir srcdir
  3. change conf.py adding my path and “napolean extension”
  4. make html