Doxygen

Doxygen is a tool to generate API documentation. It has plugins to support several languages, but is used most prominently in C/C++ projects.

Documentation

Documentation
http://www.stack.nl/~dimitri/doxygen/manual/index.html		Documentation

Install

FreeBSD

#cd /usr/ports/devel/doxygen
#make clean install 
sudo pkg install doxygen

Configuration

Create a project

Each project gets it's own config file, this creates a vanilla config.

doxygen -g mfwpython

/home/will/mfwpython

## General Project Settings
PROJECT_NAME   = "mfw python"
PROJECT_NUMBER = 0
TAB_SIZE       = 3
WARN_LOGFILE   = "/home/will/mfwpython.log"
INPUT          = "/home/will/progs/maya/m2014/pythonScriptLib"
FILE_PATTERNS  = *.py,*.pyw
RECURSIVE      = YES

HIDE_UNDOC_RELATIONS = NO
EXTRACT_STATIC       = YES
EXCLUDE_ALL          = YES    ##(TEMPORARILY)


## Python Settings
FILTER_SOURCE_FILES = YES
INPUT_FILTER        = "python2 /usr/local/bin/doxypy.py"

curl -O# https://bootstrap.pypa.io/get-pip.py
sudo pip2 install doxypy

Generate Project Documentation

doxygen mfwpython

Usage

Doxygen used with doxypy enabled will automatically read your doctags, customized doxygen parameters, and your documentation will be generated accordingly. Note that newlines are ignored, you *can* use '\n', or '<br>', but sticking everything in between'<pre>' tags will maintain your spacing and and newlines. I prefer monospaced fonts anyways.

Parameters

## Parameters are indicated by the '@' character 
@package    IMPORTANT, if you have a doctag that exists before your first 
            function, you must specify the module's name, or else your doctags will 
            all be offset. The module doctag will show up as the description for the 
            first    function.

@brief    Generates a brief description, that
            continues until the first newline

@author    Author of the script

Example Code

"""@package test.py

<pre>
Author: will pittman
desc:   blah blah blah
__________________________
date:   blah blah blah
__________________________
</pre>
"""



def main(string='abc'):
    """
    @brief Prints a string to stdout

    <pre>
    This is the long description for the function. It
    will print a string to stdout. You can use markdown syntax
    in here.

    </pre>
    """

Special doxygen parameters can be entered into your doctags. They are indicated by a '@' or a '\'.

Themes/Customization

The default doxygen theme isn't the most readable thing in the world. I started poking around to see what other people had done with it, partly to see if I might be able to grab something from elsewhere.

Source Website		Theme In Use
https://github.com/Velron/doxygen-bootstrapped/		https://biogearsengine.com/documentation/modules.html

References:

https://blogs.cs.st-andrews.ac.uk/jfdm/2013/04/04/documenting-python-using-doxygen/

http://notemagnet.blogspot.ca/2009/10/using-doxypy-for-python-code.html