Side-to-side documentation generator. Fork of the Pycco, grandfork of the Docco. And an object-oriented one.
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.
- Use
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