Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

Tree [04638a] geps/gep-006-locations / docs /
History



File Date Author Commit
corecli 2012-02-20 Jérôme Rapinat Jérôme Rapinat [e76a52] update API documentation (3.4)
coregui 2012-12-03 Jérôme Rapinat Jérôme Rapinat [79ed69] specific import path for generating GUI section
gen 2012-07-23 Benny Malengier Benny Malengier [64d2de] merged r19899 through r20053 of trunk
Makefile 2013-01-07 Nick Hall Nick Hall [37c01a] Restore Makefiles removed by mistake
README.txt 2009-08-22 Raphael Ackermann Raphael Ackermann [d0ca4b] fix typo
api.rst 2012-07-23 Benny Malengier Benny Malengier [64d2de] merged r19899 through r20053 of trunk
conf.py 2012-11-30 Jérôme Rapinat Jérôme Rapinat [a87a4f] GEP008: update references for documentation
date.rst 2012-12-03 Jérôme Rapinat Jérôme Rapinat [81172d] specific import path for Date Editor
developer_guide.rst 2009-06-24 Benny Malengier Benny Malengier [a52bc6] 2691: Create api documentation with sphinx
html.rst 2009-06-24 Benny Malengier Benny Malengier [a52bc6] 2691: Create api documentation with sphinx
index.rst 2009-06-24 Benny Malengier Benny Malengier [a52bc6] 2691: Create api documentation with sphinx
relationship.rst 2010-07-29 Jérôme Rapinat Jérôme Rapinat [a35db4] 3526:Documentation for relationship module
simple.rst 2012-07-23 Benny Malengier Benny Malengier [64d2de] merged r19899 through r20053 of trunk
update_doc.py 2013-01-20 John Ralls John Ralls [fecf9e] Fix platform detection on OSX
user_guide.rst 2009-06-24 Benny Malengier Benny Malengier [a52bc6] 2691: Create api documentation with sphinx

Read Me

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


Documentation 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 variable, :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
`