Side-to-side documentation generator. Fork of the Pycco, grandfork of the Docco. And an object-oriented one.

See how it works

Installation

Pyccoon is available on PyPi package index. You can install it using pip:

pip install pyccoon

Another way to get the Pyccoon is

git clone https://github.com/ckald/pyccoon.git
cd pyccoon
python setup.py install

And you're done. Pyccoon is compatible with Python 2.6, 2.7, 3.3, 3.4 and PyPy. Latest test results can be seen on the Travis CI project page.

Usage

To generate the project documentation

pyccoon -s <source folder> -d <documentation folder>

For additional CLI options, see pyccoon --help

At the moment Pyccoon supports Python, Ruby, Javascript, PHP and C/C++ source files. Other project files will be simply copied to the documentation folder. For additional configuration, create a config file of the kind:

# Items related to the project (currently only the name)
project:
   name: Your Project Name Goes Here
# How verbose we want Pycoon to be
verbosity: null 
# Items related to file handling
files:
   # Files Pyccoon will skip when generating the documentation.
   # Must be a list of regular expressions (not glob patterns!)
   skip:
       - "doc"
       - "\\.git*"
       - ".+\\.pyc"
   # Files that Pyccoon will copy literally
   copy:
       - "pyccoon.svg"
       - ".+\\css"
       - "\\.pyccoon.yaml"
# Items related to generation of HTML docs
documentation:
   mathjax: true
   # Can be either "pre-wrap" or "normal". Default is "normal"
   #  - "pre-wrap" respects line breaks
   linebreaking-behavior: normal
   # A path to a CSS file or 'null' (the default)
   css-path: null
   # A path to a HTML file or 'null' (the default)
   custom-html-template: null

Supported languages

It is easy to add a language to Pyccoon (pull requests are welcome!), but it requires some testing on the real-life project. By now we have worked with:

• Markdown
• Python
• Ruby (basic)
• C/C++
• Javascript
• PHP
• Fortran

Other languages are supported, but not well tested:

• PHP
• Haskell
• Lua
• Erlang
• Tcl
• CofeeScript
• Perl
• SQL
• Scheme
• Clojure

Development roadmap

• Enhancements:
  • Use glob: replace config file regular expressions with more natural wildcards (also support matching against the whole path, not only filename)
  • Add line numbers feature
  • Incremental regeneration
  • Object retrieval and cross-linking ("jump to definition" for classes, functions)
  • Search
  • Extended docblocks parsing (capturing shortcuts and aliases for cross-linking)
  • Mixed documents parsing: HTML/JS/CSS, HTML/PHP, etc.

Acknowledgements

• Cryptonomicon314 as a surprisingly enthusiastic contributor
• Nick Fitzgerald as an author of Pycco that was a starting point of the development
• Jeremy Ashkenas as an author of original idea - Docco
• Raccoon designed by Christy Presler from the Noun Project