gramps/docs
2016-05-18 20:31:49 -04:00
..
corecli 6028: same change for cli (thank you Nick); still something wrong with my config (GrampsLocale init) 2013-09-07 09:42:47 +00:00
coregui Add gui.widgets section to the documentation 2013-11-15 19:13:29 +00:00
gen 7335: Cleanup code, filenames, and documentation 2016-01-23 14:22:41 -05:00
api.rst Add gui.widgets section to the documentation 2013-11-15 19:13:29 +00:00
conf.py Update Sphinx files - includes make.bat for windows 2015-08-18 12:05:25 +10:00
date.rst 6926: merge to trunk p3: sphinx docs 2013-10-16 14:04:32 +00:00
developer_guide.rst 6028: Cleaned up and improved the Gramps API docs, Sphinx - fixed four ERROR: Unexpected indentation, added 'sphinx.ext.viewcode' to allow Sphinx to 'Add links to highlighted source code' http://sphinx-doc.org/latest/ext/viewcode.html , updated the copyright year and instructions to use pip 2014-09-29 19:51:38 +02:00
html.rst
index.rst
make.bat Update Sphinx files - includes make.bat for windows 2015-08-18 12:05:25 +10:00
Makefile Update Sphinx files - includes make.bat for windows 2015-08-18 12:05:25 +10:00
README.txt Update outdated links for http://sphinx-doc.org/ 2015-08-22 10:28:08 +10:00
relationship.rst
simple.rst
update_doc.py Clean up trailing whitespace. 2016-05-18 20:31:49 -04:00
user_guide.rst 6028: Cleaned up and improved the Gramps API docs, Sphinx - fixed four ERROR: Unexpected indentation, added 'sphinx.ext.viewcode' to allow Sphinx to 'Add links to highlighted source code' http://sphinx-doc.org/latest/ext/viewcode.html , updated the copyright year and instructions to use pip 2014-09-29 19:51:38 +02:00

Installation and building the docs
==================================

You need to install sphinx. Assuming you have installed the python setuptools, just do:

  sudo easy_install sphinx
or
  sudo pip 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-doc.org/markup/ and http://sphinx-doc.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
`