====================
Sphinkydoc |release|
====================

This is `Sphinx documentation generator`_ helper script and extension. Main 
purpose is to leverage the power of Sphinx for small Python projects. For those 
it is usually sufficient to document the code in docstrings.

Sphinkydoc also tries to address the problem that *no documentation should be 
written twice!* This is why system also tries to look for :term:`caps-files` 
in your project, such as `INSTALL`, `README`, `COPYING`, which also contain 
bits for the documentation.

Licensed under rather permissive :ref:`FreeBSD license<LICENSE>`

Usage example
=============
Lets assume you have project directory ``myproject/``.

Go to directory where you want the HTML documentation -- in this case 
``myproject/docs/`` -- and run the main script :ref:`sphinkydoc.py`::

    $ sphinkydoc.py yourmodule
    
If everything went well it should have created two directories for you 
``myproject/docs/html/`` and ``myproject/docs/_temp/``, these are deleted before 
each run. The script simply looks the :term:`caps-files` by default 
from directory *upwards from the execution directory*, you can also explicitely 
specify this directory using :option:`--caps-dir<sphinkydoc.py --caps-dir>`.

Optional *additional documentation* files are located in ``myproject/docs/``, 
and should have extension ``.rst``. If you have :term:`caps-files` 
such as ``README``, ``INSTALL``, ``AUTHORS``, ``CHANGES``, ``LICENSE`` or any 
other file that is written in uppercase, they are treated as reStructuredText
files and included to documentation, to specify files which should be treated
literally one must use :option:`-l <sphinkydoc.py -l>`.

Here is another example, executed inside ``docs/`` directory of sphinkydoc 
project, this is used to generate documentation for Sphinkydoc itself::

   $ sphinkydoc.py -s"../src/sphinkydoc.py" sphinkydocext examplepackage

Where :option:`-s<sphinkydoc.py -s>` means the next argument is some sort of 
script or executable, not necessarily Python script. First Sphinkydoc tries to 
get the :obj:`~optparser.OptionParser` of your script,
if it fails it tries to call your scripts using ``--help`` and generating 
documentation page according to that. First of the modules given is a sort of 
primary module of your project, where Sphinkydoc also looks for variables 
``__project__``, ``__version__``, ``__release__``, ``__copyright__``. If you 
type ``|release|`` in e.g. ``README``, it is rendered as same string as in 
your module. This way you can maintain version information in *one place*.

.. seealso:: :ref:`Full option listing for sphinkydoc.py <sphinkydoc.py>` in the 
	documentation.

.. _Sphinx documentation generator: http://sphinx.pocoo.org/