Documenting Python code

Documenting_Python_code.txt

This Gist is a work-in-progress.

Here are some web sites of interest:

  Example NumPy Style Python Docstrings
    http://www.sphinx-doc.org/en/1.5.1/ext/example_numpy.html
  Python Docstrings
    http://www.geeksforgeeks.org/python-docstrings/
  Google Style Guides
    https://github.com/google/styleguide
      
      def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
          """Fetches rows from a Bigtable.

          Retrieves rows pertaining to the given keys from the Table instance
          represented by big_table.  Silly things may happen if
          other_silly_variable is not None.

          Args:
              big_table: An open Bigtable Table instance.
              keys: A sequence of strings representing the key of each table row
                  to fetch.
              other_silly_variable: Another optional variable, that has a much
                  longer name than the other args, and which does nothing.

          Returns:
              A dict mapping keys to the corresponding table row data
              fetched. Each row is represented as a tuple of strings. For
              example:

              {'Serak': ('Rigel VII', 'Preparer'),
               'Zim': ('Irk', 'Invader'),
               'Lrrr': ('Omicron Persei 8', 'Emperor')}

              If a key from the keys argument is missing from the dictionary,
              then that row was not found in the table.

          Raises:
              IOError: An error occurred accessing the bigtable.Table object.
          """
          pass