Merge pull request realpython#198 from clinthowarth/master

tightened and expanded documentation page

Author: Kenneth Reitz

docs/writing/documentation.rst

@@ -1,247 +1,166 @@
-Documenting Your Code
-=====================
-
-With readability of the code being a main focus for Python developers, proper
-commenting is naturally important. Some best practice apply to code comments
-and project documents, depending on the scope of the project.
-
-Project documents
------------------
-
-A README file at the root directory give general information to the users and
-the maintainers. It should be raw text or written in some very easy to read
-markup, such as reStructuredText and Markdown. It should contain a few lines
-explaining the purpose of the project or the library (without assuming the user
-knows anything about the project), the url of the main source for the software,
-and some basic credit information. This file is the main entry point for
-readers of the code.
-
-An INSTALL file is less often necessary with python, except if the dependencies
-are complex or unusual, or if some C modules need to be compiled before use.
-The installation instructions are often reduced to one command, such as ``pip
-install module`` or ``python setup.py install`` and added to the README file.
-
-A LICENSE file should always be present and specify the license under which the
+Documentation
+=============
+
+Readability is a primary focus for Python developers, in both project
+and code documentation. Following some simple best practices can save
+both you and others a lot of time.
+
+Project Documentation
+---------------------
+
+A ``README`` file at the root directory should give general
+information to the users and the maintainers. It should be raw text or
+written in some very easy to read markup, such as
+:ref:`reStructuredText-ref` and Markdown. It should contain a few
+lines explaining the purpose of the project or the library (without
+assuming the user knows anything about the project), the url of the
+main source for the software, and some basic credit information. This
+file is the main entry point for readers of the code.
+
+An ``INSTALL`` file is less necessary with python.  The installation
+instructions are often reduced to one command, such as ``pip install
+module`` or ``python setup.py install`` and added to the ``README``
+file.
+
+A ``LICENSE`` file should *always* be present and specify the license under which the
 software is made available to the public.
 
-A TODO file or a TODO section in README should list the planned modifications
-of the code.
+A ``TODO`` file or a ``TODO`` section in ``README`` should list the
+planned development for the code.
 
-A CHANGELOG file or section in README should compile a short overview of the
-changes in the code base for the latest versions.
+A ``CHANGELOG`` file or section in ``README`` should compile a short
+overview of the changes in the code base for the latest versions.
 
-Documentation
--------------
-
-As the project or library reaches a certain level of complexity, it may require
-a fuller documentation, which can be of different flavors:
-
-The introduction may show a very short overview of what can be done with the
-product, using one or two extremely simplified use cases.
-
-The tutorials will show in more details some main use cases. The reader will
-follow a step-by-step procedure to set-up a working prototype.
+Project Publication
+-------------------
 
-The API reference, which is often generated automatically from the code, will
-list all publicly available interfaces, their parameters and their return
-values, with an explanation of their use.
+Depending on the project, your documentation might include some or all
+of the following components:
 
-Some documents intended for developers might give guidance about code
-convention and general design decision of the project.
+- A *introduction* should show a very short overview of what can be
+  done with the product, using one or two extremely simplified use
+  cases. This is the thirty-second pitch for your project.
 
-Comments
---------
+- A *tutorial* should show some primary use cases in more detail. The reader will
+  follow a step-by-step procedure to set-up a working prototype.
 
-Comments are written directly inside the code, either using the hash sign (#)
-or a docstring_.
-
-.. _docstring: docstrings_
+- An *API reference* is typically generated from the code (see
+  :ref:`docstrings <docstring-ref>`). It will list all publicly available interfaces,
+  parameters, and return values.
 
-Finding the correct balance between undocumented code and verbose and useless
-comment boilerplates is difficult, and is the subject of heated discussion
-among developers.
+- *Developer documentation* is intended for potential contributors. This can
+  include code convention and general design strategy of the project.
 
-The following guidelines seem to be most commonly agreed upon:
-
-**Wrong or outdated comments are worse than no comments at all.** Following the
-saying that it is better, on a boat, to know that we do not know were we are
-than to wrongly believe we know where we are, wrong or outdated comments can be
-misleading for the maintainers, slow down considerably bug hunting or
-refactoring, and then, when discovered wrong, they will throw suspicion on all
-other comments in the code, regardless of their individual correctness.
-
-**There's no need to comment perfect code...** An hypothetical perfectly readable
-code, with a crystal clear logic stream, expressive variable and function
-names, orthogonal segmentation passing exactly between the flesh and the bones,
-and no implicit assumptions of any kind, would not require any comment at all.
-When striving for coding excellence, it is useful to see any existing comment,
-or any feeling of a need for a comment, as the sign that the code do not
-express clearly enough its intent and can be improved.
-
-**.. but no code is perfect.**  Perfect code is a chimera, it exists only in
-our dreams.  In real life, a code base is full of trade offs, and comments are
-often needed in the most difficult parts. Moreover, any special case, any
-obscure hack, any monkey patch and any ugly workaround MUST be signaled and
-explained by a proper comment. This should be enforced by the law!
-
-**TODOs** are special comments that a developer write as a reminder for later
-use. It is said that its original intent was that someone might, one day,
-search for the string "TODO" in the code base and actually roll their sleeves
-and start *to do the TODOs*. There is no available record that it ever
-happened. However, TODOs comment are still very useful, because they mark the
-current limits of the code, and it is not unlikely that, when required to add a
-new behavior to the actual code, looking at the TODOs will show where to start.
-
-**Do not use triple-quote strings to comment code.** A common operation when
-modifying code is to comment out some lines or even a full function or class
-definition. This can be done by adding triple-quotes around the code block to
-be skipped, but this is not a good practice, because line-oriented command-line
-tools such as ``grep`` will not be aware that the commented code is inactive.
-It is better to add hashes at the proper indentation level for every commented
-line. Good editors allow to do this with few keystrokes (ctrl-v on Vim).
-
-**Bad**
-
-.. code-block:: python
-
-    def tricky_function():
-        '''
-        Commented out because its breaks something.
-        if foo:
-            do_bar()
-        '''
-        return baz
-
-    def tricky_function():
-        # Commented out because its breaks something.
-        #if foo:
-            #do_bar()
-        return baz
-
-
-    def tricky_function():
-    # Commented out because its breaks something.
-    #   if foo:
-    #       do_bar()
-        return baz
-
-**Good**
-
-.. code-block:: python
-
-    def tricky_function():
-        # Commented out because its breaks something.
-        #if foo:
-        #    do_bar()
-        return baz
-
-Note that comment text is properly written and separated from the hash by a
-space. Commented code is not separated from the hash by an additional space;
-this helps when uncommented the code.
-
-The Basics
-::::::::::
-
-
-Code Comments
--------------
-
-Information regarding code comments is taken from PEP 008 (http://www.python.org/dev/peps/pep-0008/).
-Block comment styling should be used when commenting out multiple lines of code.: ::
-
-    Block comments generally apply to some (or all) code that follows them,
-    and are indented to the same level as that code.  Each line of a block
-    comment starts with a # and a single space (unless it is indented text
-    inside the comment).
-    Paragraphs inside a block comment are separated by a line containing a
-    single #.
-
-In-line comments are used for individual lines and should be used sparingly.: ::
-
-    An inline comment is a comment on the same line as a statement.  Inline
-    comments should be separated by at least two spaces from the statement.
-    They should start with a # and a single space.
-    Inline comments are unnecessary and in fact distracting if they state
-    the obvious.  Don't do this:
-        x = x + 1                 # Increment x
-    But sometimes, this is useful: ::
-        x = x + 1                 # Compensate for border
-
-Docstrings
------------
+.. _sphinx-ref:
 
-PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/)
+Sphinx
+~~~~~~
 
-There are two types of docstrings, one-line and multi-line.  Their names
-should be fairly self explanatory.
-One-line docstrings: ::
+Sphinx_ is far and away the most popular python documentation
+tool. **Use it.**  It converts :ref:`restructuredtext-ref` markup language
+into a range of output formats including HTML, LaTeX (for printable
+PDF versions), manual pages, and plain text.
 
-    def kos_root():
-        """Return the pathname of the KOS root directory."""
-        global _kos_root
-        if _kos_root: return _kos_root
-        ...
+There is also **great**, **free** hosting for your Sphinx_ docs:
+`Read The Docs`_. Use it. You can configure it with commit hooks to
+your source repository so that rebuilding your documentation will
+happen automatically.
 
-Multi-line docstrings: ::
+.. note::
 
-    def complex(real=0.0, imag=0.0):
-        """Form a complex number.
+    Sphinx is famous for its API generation, but it also works well
+    for general project documentation. This Guide is built with
+    Sphinx_ and is hosted on `Read The Docs`_
 
-        Keyword arguments:
-        real -- the real part (default 0.0)
-        imag -- the imaginary part (default 0.0)
+.. _Sphinx: http://sphinx.pocoo.org
+.. _Read The Docs: http://readthedocs.org
 
-        """
-        if imag == 0.0 and real == 0.0: return complex_zero
-        ...
+.. _restructuredtext-ref:
 
+reStructuredText
+~~~~~~~~~~~~~~~~
 
-.. _sphinx-ref:
+Most Python documentation is written with reStructuredText_. It's like
+Markdown with all the optional extensions built in.
 
+The `reStructuredText Primer`_ and the `reStructuredText Quick
+Reference`_ should help you familiarize yourself with its syntax.
 
-Sphinx
-------
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _reStructuredText Primer: http://sphinx.pocoo.org/rest.html
+.. _reStructuredText Quick Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html
 
-Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref`
-markup language into a range of output formats including HTML, LaTeX (for
-printable PDF versions), manual pages and plain text.
 
-There is also a great free hosting for your Sphinx_ docs: `Read The Docs`_
+Code Documentation Advice
+-------------------------
 
-.. note:: This Guide is built with Sphinx_ and hosted on `Read The Docs`_
+Comments clarify code and begin with a hash (``#``).
 
-.. _Sphinx: http://sphinx.pocoo.org
-.. _Read The Docs: http://readthedocs.org
+.. _docstring-ref:
 
-.. _restructuredtext-ref:
+In Python, *docstrings* describe modules, classes, and functions: ::
 
+    def square_and_rooter(x):
+        """Returns the square root of self times self."""
+        ...
 
-reStructuredText
-----------------
+In general, follow the `comment section of PEP 0008`_ (the "Python Style Guide").
 
-Most Python documentation is written with reStructuredText_. The
-`reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`_ and the
-`reStructuredText Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
-should help you familiarize yourself with its syntax.
+.. _comment section of PEP 0008: http://www.python.org/dev/peps/pep-0008/#comments
+
+Commenting Sections of Code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Do not use triple-quote strings to comment code*. This is not a good
+practice, because line-oriented command-line tools such as grep will
+not be aware that the commented code is inactive. It is better to add
+hashes at the proper indentation level for every commented line. Your
+editor probably has the ability to do this easily, and it is worth
+learning the comment/uncomment toggle. (*e.g.* ctrl-v on Vim)
+
+Docstrings and Magic
+~~~~~~~~~~~~~~~~~~~~
+
+Some tools use docstrings to embed more-than-documentation behavior,
+such as unit test logic. Those can be nice, but you won't ever go
+wrong with vanilla "here's what this does."
+
+Docstrings versus Block comments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These aren't interchangeable. For a function or class, the leading
+comment block is a programmer's note. The docstring describes the
+operation of the function or class: ::
+
+    # This function slows down program execution for some reason.
+    def square_and_rooter(x):
+        """Returns the square root of self times self."""
+	...
+
+.. seealso:: Further reading on docstrings: `PEP 0257`_
+
+.. _PEP 0257: http://www.python.org/dev/peps/pep-0257/
 
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
 Other Tools
-:::::::::::
+-----------
+
+You might see these in the wild. Use :ref:`sphinx-ref`.
+
+Pycco_
+    Pycco is a "literate-programming-style documentation generator"
+    and is a port of the node.js Docco_. It makes code into a
+    side-by-side HTML code and documentation.
 
+.. _Pycco: http://fitzgen.github.com/pycco
+.. _Docco: http://jashkenas.github.com/docco
 
-Epydoc
-------
-`Epydoc <http://epydoc.sourceforge.net/>`_ generates API documentation based on docstrings. 
-Epydoc is able to parse docstrings marked up with :ref:`reStructuredText-ref`, 
-`Javadoc <http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html#javadocdocuments>`_, 
-`epytext <http://epydoc.sourceforge.net/manual-epytext.html>`_ or plaintext. 
-It supports various output formats, most notable HTML, PDF or LaTeX documents.
+Ronn_
+    Ronn builds unix manuals. It converts human readable textfiles to roff for terminal display, and also to HTML for the web.
 
-The development of Epydoc is discontinued. You should use :ref:`sphinx-ref` instead.
+.. _Ronn: https://github.com/rtomayko/ronn
 
-pycco / docco / shocco
-----------------------
+Epydoc_
+    Epydoc is discontinued. Use :ref:`sphinx-ref` instead.
 
-Ronn
-----
+.. _Epydoc: http://epydoc.sourceforge.net