docs/writing/documentation.rst

   1 Documentation
   2 =============
   3
   4 Readability is a primary focus for Python developers, in both project
   5 and code documentation. Following some simple best practices can save
   6 both you and others a lot of time.
   7
   8 Project Documentation
   9 ---------------------
  10
  11 A ``README`` file at the root directory should give general
  12 information to the users and the maintainers. It should be raw text or
  13 written in some very easy to read markup, such as
  14 :ref:`reStructuredText-ref` and Markdown. It should contain a few
  15 lines explaining the purpose of the project or the library (without
  16 assuming the user knows anything about the project), the url of the
  17 main source for the software, and some basic credit information. This
  18 file is the main entry point for readers of the code.
  19
  20 An ``INSTALL`` file is less necessary with python.  The installation
  21 instructions are often reduced to one command, such as ``pip install
  22 module`` or ``python setup.py install`` and added to the ``README``
  23 file.
  24
  25 A ``LICENSE`` file should *always* be present and specify the license under which the
  26 software is made available to the public.
  27
  28 A ``TODO`` file or a ``TODO`` section in ``README`` should list the
  29 planned development for the code.
  30
  31 A ``CHANGELOG`` file or section in ``README`` should compile a short
  32 overview of the changes in the code base for the latest versions.
  33
  34 Project Publication
  35 -------------------
  36
  37 Depending on the project, your documentation might include some or all
  38 of the following components:
  39
  40 - A *introduction* should show a very short overview of what can be
  41   done with the product, using one or two extremely simplified use
  42   cases. This is the thirty-second pitch for your project.
  43
  44 - A *tutorial* should show some primary use cases in more detail. The reader will
  45   follow a step-by-step procedure to set-up a working prototype.
  46
  47 - An *API reference* is typically generated from the code (see
  48   :ref:`docstrings <docstring-ref>`). It will list all publicly available interfaces,
  49   parameters, and return values.
  50
  51 - *Developer documentation* is intended for potential contributors. This can
  52   include code convention and general design strategy of the project.
  53
  54 .. _sphinx-ref:
  55
  56 Sphinx
  57 ~~~~~~
  58
  59 Sphinx_ is far and away the most popular python documentation
  60 tool. **Use it.**  It converts :ref:`restructuredtext-ref` markup language
  61 into a range of output formats including HTML, LaTeX (for printable
  62 PDF versions), manual pages, and plain text.
  63
  64 There is also **great**, **free** hosting for your Sphinx_ docs:
  65 `Read The Docs`_. Use it. You can configure it with commit hooks to
  66 your source repository so that rebuilding your documentation will
  67 happen automatically.
  68
  69 .. note::
  70
  71     Sphinx is famous for its API generation, but it also works well
  72     for general project documentation. This Guide is built with
  73     Sphinx_ and is hosted on `Read The Docs`_
  74
  75 .. _Sphinx: http://sphinx.pocoo.org
  76 .. _Read The Docs: http://readthedocs.org
  77
  78 .. _restructuredtext-ref:
  79
  80 reStructuredText
  81 ~~~~~~~~~~~~~~~~
  82
  83 Most Python documentation is written with reStructuredText_. It's like
  84 Markdown with all the optional extensions built in.
  85
  86 The `reStructuredText Primer`_ and the `reStructuredText Quick
  87 Reference`_ should help you familiarize yourself with its syntax.
  88
  89 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  90 .. _reStructuredText Primer: http://sphinx.pocoo.org/rest.html
  91 .. _reStructuredText Quick Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html
  92
  93
  94 Code Documentation Advice
  95 -------------------------
  96
  97 Comments clarify code and begin with a hash (``#``).
  98
  99 .. _docstring-ref:
 100
 101 In Python, *docstrings* describe modules, classes, and functions: ::
 102
 103     def square_and_rooter(x):
 104         """Returns the square root of self times self."""
 105         ...
 106
 107 In general, follow the `comment section of PEP 0008`_ (the "Python Style Guide").
 108
 109 .. _comment section of PEP 0008: http://www.python.org/dev/peps/pep-0008/#comments
 110
 111 Commenting Sections of Code
 112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 113
 114 *Do not use triple-quote strings to comment code*. This is not a good
 115 practice, because line-oriented command-line tools such as grep will
 116 not be aware that the commented code is inactive. It is better to add
 117 hashes at the proper indentation level for every commented line. Your
 118 editor probably has the ability to do this easily, and it is worth
 119 learning the comment/uncomment toggle. (*e.g.* ctrl-v on Vim)
 120
 121 Docstrings and Magic
 122 ~~~~~~~~~~~~~~~~~~~~
 123
 124 Some tools use docstrings to embed more-than-documentation behavior,
 125 such as unit test logic. Those can be nice, but you won't ever go
 126 wrong with vanilla "here's what this does."
 127
 128 Docstrings versus Block comments
 129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 130
 131 These aren't interchangeable. For a function or class, the leading
 132 comment block is a programmer's note. The docstring describes the
 133 operation of the function or class: ::
 134
 135     # This function slows down program execution for some reason.
 136     def square_and_rooter(x):
 137         """Returns the square root of self times self."""
 138         ...
 139
 140 .. seealso:: Further reading on docstrings: `PEP 0257`_
 141
 142 .. _PEP 0257: http://www.python.org/dev/peps/pep-0257/
 143
 144
 145 Other Tools
 146 -----------
 147
 148 You might see these in the wild. Use :ref:`sphinx-ref`.
 149
 150 Pycco_
 151     Pycco is a "literate-programming-style documentation generator"
 152     and is a port of the node.js Docco_. It makes code into a
 153     side-by-side HTML code and documentation.
 154
 155 .. _Pycco: http://fitzgen.github.com/pycco
 156 .. _Docco: http://jashkenas.github.com/docco
 157
 158 Ronn_
 159     Ronn builds unix manuals. It converts human readable textfiles to roff for terminal display, and also to HTML for the web.
 160
 161 .. _Ronn: https://github.com/rtomayko/ronn
 162
 163 Epydoc_
 164     Epydoc is discontinued. Use :ref:`sphinx-ref` instead.
 165
 166 .. _Epydoc: http://epydoc.sourceforge.net