2691: Create api documentation with sphinx

svn: r12704

docs/README.txt

@@ -0,0 +1,72 @@
+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
+`