========
RefBuild
========

RefBuild is a utility that builds reStructuredText files from the docstrings
of a project's Python source files and prepares them for compilation with Sphinx.

To use, navigate to the folder containing the source files to read from. Open a
command line at this directory and execute the command::

  $ buildref

You will be prompted to give the output folder. If your project directory is::

  /packageroot
      /doc
          /source
              index.rst
      /src
          main.py
          othersource.py

you should execute refbuild from the ``src`` directory and type ``../doc/source``
for the source of the output folder. Afterwards, you will have the following files::

  /packageroot
      /doc
          /source
              api.rst
              index.rst
              main.py
              othersource.py
      /src
          main.py
          othersource.py

Installation
------------

To install (possibly as root) from the Python Package Index::

  $ pip install refbuild

  or

  $ easy_install refbuild

If you have downloaded the source package, extract and::

  $ python setup.py install

Again, you might have to install as root.

Documentation
-------------

You can build the documentation with a command line in the "doc" folder::

  $ make html

This will create a "build" directory and in there will be the documentation.
The "api.rst" and "refbuild.rst" file were created with this tool.


