git://developer.intra2net.com / pyi2ncommon / blame
| Commit | Line | Data |
|---|---|---|
| e0137244 CH |
1 | About this documentation |
| 2 | ======================== | |
| 3 | ||
| 4 | ||
| 5 | How to generate this documentation | |
| 6 | ---------------------------------- | |
| 7 | ||
| 8 | * Install Sphinx | |
| adcc015e CH |
9 | * change dir to project main dir |
| 10 | * create symlink: ``ln -s src pyi2ncommon`` | |
| e0137244 | 11 | * change dir into doc |
| adcc015e | 12 | * run ``sphinx-apidoc -o ./ ../pyi2ncommon`` |
| 47df0969 | 13 | (you may have to add a -f if you added a new module) |
| adcc015e | 14 | * run ``make html`` |
| db622927 CH |
15 | (this will create one .rst file for each python file in pyi2ncommon directory) |
| 16 | ||
| e0137244 | 17 | |
| db622927 CH |
18 | Good to know |
| 19 | ------------ | |
| e0137244 | 20 | |
| 47df0969 | 21 | * lots of example documentation can be found in the docu of template.py (:py:mod:`template`) |
| db622927 CH |
22 | * this Documentation was initialized using sphinx-quickstart |
| 23 | * doc/conf.py can be used to configure lots of the documentation | |
| 24 | * the autodoc extension is responsible for creating .rst files from documentation in .py files | |
| 25 | * you should not have to change the my_module_name.rst files or modules.rst since they are auto-created | |
| 26 | * by including modules.rst in the toctree of index.rst, all modules' source doc is included in this help | |
| 27 | * in conf.py, there is a setup() function in the end which can be used to influence the doc strings | |
| 28 | * sometimes, adding . to the end of list items is required (not always as in this example) | |
| e0137244 | 29 | |
| e0137244 CH |
30 | |
| 31 | TODO | |
| 32 | ---- | |
| 33 | ||
| db622927 CH |
34 | * before committing run pylint and pep8 (--> check.sh) |
| 35 | * automatically get classes and exceptions (and free functions?) into sidebar when opening module doc | |
| 36 | * automatically set module name as title for module doc |