Documenting Tools
=================

Please add script docstrings, and pass them through to GGO through:

.. code:: python

      doc=__doc__,

In Galaxy
---------

Command line in galaxy is converted straight from restructured text in
the docstring into the ``<help />`` section of a galaxy tool:

.. code:: xml

      </outputs>
      <help>Example utility to test many different combinations of parameters and parameter types.

    From Wikipedia:

        The docstring of a script (a stand-alone program) should be usable as its
        "usage" message, printed when the script is invoked with incorrect or missing
        arguments (or perhaps with a "-h" option, for "help"). Such a docstring should
        document the script's function and command line syntax, environment variables,
        and files. Usage messages can be fairly elaborate (several screens full) and
        should be sufficient for a new user to use the command properly, as well as a
        complete quick reference to all options and arguments for the sophisticated
        user. If the stand-alone script uses another module for handling options, such
        as the argparse module, then option information is moved from the docstring to
        the modules utilities.

    Thanks to the functionality of GGO, it is sufficient to write only the
    documentation for how the script should be used, and to skip writing
    documentation for command line parameters. Those are handled automatically
    based on data in the instantiation of GGO
    </help>
      <tests>

At the Command Line
-------------------

Command line documentation (similar to man pages/perldoc) is available
via ``pydoc``

.. code:: bash

    Help on module complex:

    NAME
        complex - Example utility to test many different combinations of parameters and parameter types.

    FILE
        complex.py

    DESCRIPTION
        From Wikipedia:

            The docstring of a script (a stand-alone program) should be usable as its
            "usage" message, printed when the script is invoked with incorrect or missing
            arguments (or perhaps with a "-h" option, for "help"). Such a docstring should
            document the script's function and command line syntax, environment variables,
            and files. Usage messages can be fairly elaborate (several screens full) and
            should be sufficient for a new user to use the command properly, as well as a
            complete quick reference to all options and arguments for the sophisticated
            user. If the stand-alone script uses another module for handling options, such
            as the argparse module, then option information is moved from the docstring to
            the modules utilities.
        
        Thanks to the functionality of GGO, it is sufficient to write only the
        documentation for how the script should be used, and to skip writing
        documentation for command line parameters. Those are handled automatically
        based on data in the instantiation of GGO

    FUNCTIONS
        main()