72 lines
1.8 KiB
Plaintext
72 lines
1.8 KiB
Plaintext
|
Installation and building the docs
|
||
|
|
==================================
|
||
|
|
|
||
|
|
You need to install sphinx. Assuming you have installed the python setuptools, just do:
|
||
|
|
|
||
|
|
sudo easy_install sphinx
|
||
|
|
|
||
|
|
Once installed, go to the docs directory, and do:
|
||
|
|
|
||
|
|
make html
|
||
|
|
|
||
|
|
Which will produce the html output in docs/_build/html
|
||
|
|
|
||
|
|
|
||
|
|
Documention Guidelines
|
||
|
|
=======================
|
||
|
|
|
||
|
|
Doc strings in python files should be written in reStructured text: http://docutils.sourceforge.net/docs/user/rst/quickref.html
|
||
|
|
|
||
|
|
The typical docstring for GRAMPS should look like this:
|
||
|
|
|
||
|
|
"""Brief synopsis
|
||
|
|
|
||
|
|
This is a longer explanation, which may include *italics* or **bold**, or
|
||
|
|
a link to another method :meth:`~gen.lib.person.Person.get_handle`
|
||
|
|
Then, you need to provide optional subsection in this order (just to be
|
||
|
|
consistent and have a uniform documentation, nothing prevent you to switch
|
||
|
|
the order).
|
||
|
|
|
||
|
|
:param arg1: the first value
|
||
|
|
:type arg1: int or float or :class:`~gen.lib.baseobj.BaseObject`
|
||
|
|
:param arg2: the second value
|
||
|
|
:type arg2: int or float
|
||
|
|
:param arg3: the third value
|
||
|
|
|
||
|
|
:returns: arg1/arg2 +arg3
|
||
|
|
:rtype: float, this is the return type
|
||
|
|
|
||
|
|
|
||
|
|
:Examples:
|
||
|
|
|
||
|
|
>>> import template
|
||
|
|
>>> a = MainClass()
|
||
|
|
>>> a.function2(1,1,1)
|
||
|
|
2
|
||
|
|
|
||
|
|
:note:
|
||
|
|
can be useful to emphasize
|
||
|
|
important feature
|
||
|
|
|
||
|
|
:See Also:
|
||
|
|
:class:`MainClass1`
|
||
|
|
|
||
|
|
:Warnings:
|
||
|
|
arg2 must be non-zero.
|
||
|
|
|
||
|
|
:Todo:
|
||
|
|
check that arg2 is non zero.
|
||
|
|
"""
|
||
|
|
|
||
|
|
For a class, use :cvar variable: for class variaable, :ivar variable: for instance class
|
||
|
|
variable, .. attribute:: attribute: for attributes, ....
|
||
|
|
See http://sphinx.pocoo.org/markup/desc.html and http://sphinx.pocoo.org/markup/inline.html
|
||
|
|
|
||
|
|
Tips and Tricks
|
||
|
|
===============
|
||
|
|
Change in many files something:
|
||
|
|
|
||
|
|
perl -pi -w -e "s/L{PersonRef}/:class:\`\~gen.lib.personref.PersonRef\`/g;" *.py
|
||
|
|
|
||
|
|
here L{PersonRef} is changed in :class:`~gen.lib.personref.PersonRef
|
||
|
|
`
|