[pyi2ncommon] / doc / about_docu.rst

About this documentation
========================


How to generate this documentation
----------------------------------

* Install Sphinx
* change dir to project main dir
* create symlink: ``ln -s src pyi2ncommon``
* change dir into doc
* run ``sphinx-apidoc -o ./ ../pyi2ncommon``
  (you may have to add a -f if you added a new module)
* run ``make html``
  (this will create one .rst file for each python file in pyi2ncommon directory)


Good to know
------------

* lots of example documentation can be found in the docu of template.py (:py:mod:`template`)
* this Documentation was initialized using sphinx-quickstart
* doc/conf.py can be used to configure lots of the documentation
* the autodoc extension is responsible for creating .rst files from documentation in .py files
* you should not have to change the my_module_name.rst files or modules.rst since they are auto-created
* by including modules.rst in the toctree of index.rst, all modules' source doc is included in this help
* in conf.py, there is a setup() function in the end which can be used to influence the doc strings
* sometimes, adding . to the end of list items is required (not always as in this example)


TODO
----

* before committing run pylint and pep8 (--> check.sh)
* automatically get classes and exceptions (and free functions?) into sidebar when opening module doc
* automatically set module name as title for module doc
Commit	Line	Data
	1	About this documentation
	2	========================
	3
	4
	5	How to generate this documentation
	6	----------------------------------
	7
	8	* Install Sphinx
	9	* change dir to project main dir
	10	* create symlink: ``ln -s src pyi2ncommon``
	11	* change dir into doc
	12	* run ``sphinx-apidoc -o ./ ../pyi2ncommon``
	13	(you may have to add a -f if you added a new module)
	14	* run ``make html``
	15	(this will create one .rst file for each python file in pyi2ncommon directory)
	16
	17
	18	Good to know
	19	------------
	20
	21	* lots of example documentation can be found in the docu of template.py (:py:mod:`template`)
	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)
	29
	30
	31	TODO
	32	----
	33
	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