Changes

This will guide your through how to write docs for a module in sugar3.  There are 5 easy steps to writing the documentation, and 3 bonus steps for getting it merged.

This will guide you through how to write docs for a module in sugar3.  There are 5 easy steps to writing the documentation, and 3 bonus steps for getting it merged.

Example patch:  https://github.com/sugarlabs/sugar-toolkit-gtk3/pull/269/files or https://github.com/sugarlabs/sugar-toolkit-gtk3/pull/256/files

Example patch:  https://github.com/sugarlabs/sugar-toolkit-gtk3/pull/269/files or https://github.com/sugarlabs/sugar-toolkit-gtk3/pull/256/files

= How To Guide =

= How To Guide =

1.  Write a code example for using the code.  Try to write a stand alone python script that demonstrates the major features of the module and put in the ''examples'' directory in sugar-toolkit-gtk3.  If it can not be demonstrated standalone, write a code sample that the user could paste into their activity, simmilar to the ''sugar3.graphics.alert'' example.  When writing the example, add comments to explain what code is doing that might be non obvious (eg. that something is zero indexed, or that this function needs to be called first)

1.  Write a code example for using the code.  Try to write a stand alone python script that demonstrates the major features of the module and put in the ''examples'' directory in sugar-toolkit-gtk3.  If it can not be demonstrated standalone, write a code sample that the user could paste into their activity, like the ''sugar3.graphics.alert'' example.  When writing the example, add comments to explain what code is doing that might be non obvious (eg. that something is zero indexed, or that this function needs to be called first)

2.  Write a blurb (a small paragraph, around 3 lines) for the module and include your example.  Your blurb should say what this does and where to use it.  Place this between the license and the imports.  Including the example will always use the syntax ''.. literalinclude:: ../examples/SOMETHING.py''.  For example:

2.  Write a blurb (a small paragraph, around 3 lines) for the module and include your example.  Your blurb should say what this does and where to use it.  Place this between the license and the imports.  Including the example will always use the syntax ''.. literalinclude:: ../examples/SOMETHING.py''.  For example:

         return row[0]</pre>

         return row[0]</pre>

5.  '''Proofread'''.  Use the 'make-doc.sh' script to build the docs.  Then ''cd doc/_build/html'' and start a http server (''python -m SimpleHTTPServer 8000'').  Load 'localhost:8000'' in your favorite web browser and check that your documentation has rendered correctly and makes sense.  Make sure you have a spell checker in your text editor (the vim one in very nice as it only checks strings and docstrings), because I can't spell or check.

5.  '''Proofread'''.  Use the 'make-doc.sh' script to build the docs.  Then ''cd doc/_build/html'' and start a http server (''python -m SimpleHTTPServer 8000'').  Load ''localhost:8000'' in your favorite web browser and check that your documentation has rendered correctly and makes sense.  Make sure you have a spell checker in your text editor (the vim one in very nice as it only checks strings and docstrings), because I can't spell or check.

[[User:SAMdroid|SAMdroid]] ([[User talk:SAMdroid|talk]]) I'm being hypocritical saying this, but I'll proof it soon :)

[[User:SAMdroid|SAMdroid]] ([[User talk:SAMdroid|talk]]) I'm being hypocritical saying this, but I'll proof it soon :)

6.  Write a commit message like ''Write documentation for sugar3.i.just.wrote.docs''.

6.  Write a commit message like ''Write documentation for sugar3.path.module''.

7.  Create a pull request on GitHub.

7.  Create a pull request on GitHub.

reStructuredText primer:  http://sphinx-doc.org/rest.html

reStructuredText primer:  http://sphinx-doc.org/rest.html

how do I go X in sphinx?:  I'm too lazy to find docs.  Just duckduckgo or google "sphinx X" if you haven't already.

How do I do X in sphinx?:  I'm too lazy to find docs.  Just duckduckgo or google "sphinx X" if you haven't already.