Apydia - Getting Started

Getting Started

Using the command line interface

Once Apydia is installed, you will need a project to generate API documentation for. I you don't have one and still want to try out Apydia, you can generate Apydia's API docs to have a quick peek.

The fastest way to get started is to use the apydia command line tool, like this:

apydia -o {module}

This will create API reference documentation for a given module and its descendants and open the root module's page in your system's default web browser.

apydia --help

This will dump a list of availlable options:

Usage: apydia [options] [modules]

    Apydia API Documentation Generator

    Options:
      --version             show program's version number and exit
      -h, --help            show this help message and exit
      -c CONFIGFILE, --config=CONFIGFILE
                            specify config file
      -d DESTINATION, --destination=DESTINATION
                            specify output directory
      -o, --open            open in browser
      -f FORMAT, --format=FORMAT
                            rendering format (xhtml or html,
                            defaults to xhtml)
      -s THEME, --style=THEME
                            Choose a theme
      -p DOCFORMAT, --parser=DOCFORMAT
                            docstring parser (markdown, textile,
                            restructuredtext, html, ...)
      -b TRAC_BROWSER_URL, --trac-browser-url=TRAC_BROWSER_URL
                            trac browser url (path to root module)
      -q, --quiet           silent mode
      -t TITLE, --title=TITLE
                            title of project
      -x EXCLUDE_MODULES, --exclude-modules=EXCLUDE_MODULES
                            exclude modules

For example, to generate Apydia's own API documentation using its own theme, which you can see on this website, simply make sure you have the markdown-module installed and type:

apydia -o -s apydia apydia

Or, if you have Elixir installed, try the following - the Elixir-theme is bundled with Apydia for demonstration purposes, but you need to have docutils installed for this one):

apydia -o -s elixir -p restructuredtext elixir

By default documentation for all submodules will be generated, which might not be suitable in all situations. You can exclude specific modules using the -x option, like so:

apydia -o -s elixir -p restructuredtext -x elixir.statements elixir

If you need to exclude more than one module, simply add multiple -x options.

Using a configuration file

Typing all those commandline options over and over might possibly become annoying at some point. You can create some .ini-file and put all of the options in there:

[apydia]
title = Elixir
destination = apidocs
theme = elixir
docformat = reStructuredText

modules = elixir, elixir.ext.associable, elixir.ext.versioned,
          elixir.ext.encrypted
exclude_modules = elixir.statements

trac_browser_url =
    http://elixir.ematia.de/trac/browser/elixir/tags/0.4.0/elixir

Then hand it over to Apydia (assuming the filename is elixir.ini, you can of course call it whatever you like):

apydia -c elixir.ini

Integration with distutils

This is the recommended way of using Apydia, especially if your project makes use of distutils. All you have to do to make it work is to modify or create the setup.cfg file of your project (the file sould reside in the same directory like setup.py) and append lines like these:

[apydia]
title = My Example Project
theme = default
docformat = Markdown
modules = myproject
exclude_modules = myproject.somemodule, myproject.someother
trac_browser_url = http://myproject.tld/trac/browser/trunk

Now you can always generate your API reference by issuing from your project's root:

python setup.py apydia

That's it. Maybe you want to create custom themes to nicely fit your project's homepage. To see how you can accomplish this have a look at the bundled "apydia" and "elixir" themes.