Features/Sugar3 Docs/How To Write - Revision history

Quozl at 03:38, 2 January 2017

2017-01-02T03:38:56Z

← Older revision		Revision as of 23:38, 1 January 2017
Line 74:		Line 74:
	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.
Line 92:		Line 92:
	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.

Quozl at 03:36, 2 January 2017

2017-01-02T03:36:18Z

← Older revision		Revision as of 23:36, 1 January 2017
Line 6:		Line 6:
	= 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:

Quozl at 02:46, 2 January 2017

2017-01-02T02:46:35Z

← Older revision		Revision as of 22:46, 1 January 2017
Line 1:		Line 1:

	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

FGrose: FGrose moved page Features/Sugar3Docs/HowToWrite to Features/Sugar3 Docs/How To Write: deCamelCase to support wiki word searching

2015-12-29T18:25:02Z

FGrose moved page Features/Sugar3Docs/HowToWrite to Features/Sugar3 Docs/How To Write: deCamelCase to support wiki word searching

← Older revision	Revision as of 14:25, 29 December 2015
(No difference)

Quozl: typo in script name may have caused question

2015-12-29T10:57:58Z

typo in script name may have caused question

← Older revision		Revision as of 06:57, 29 December 2015
Line 74:		Line 74:
	return row[0]</pre>		return row[0]</pre>

	5. '''Proofread'''. Use the '~~make_docs~~.sh' 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 :)

Quozl at 01:42, 28 December 2015

2015-12-28T01:42:45Z

← Older revision		Revision as of 21:42, 27 December 2015
Line 80:		Line 80:
	6. Write a commit message like ''Write documentation for sugar3.i.just.wrote.docs''.		6. Write a commit message like ''Write documentation for sugar3.i.just.wrote.docs''.

	7. Create a pull request on GitHub~~, and make sure to add the ''doc'' label while you are making it~~.		7. Create a pull request on GitHub.

	8. Listen to whoever reviews your patch.		8. Listen to whoever reviews your patch.

SAMdroid: Add a note about adding the doc label

2015-11-17T08:14:32Z

Add a note about adding the doc label

← Older revision		Revision as of 04:14, 17 November 2015
Line 1:		Line 1:

	This will guide your through how to write docs for a module in sugar3. There are 5 easy steps to writing the documentation, and 2 bonus steps for getting it merged.		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.

	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
Line 80:		Line 80:
	6. Write a commit message like ''Write documentation for sugar3.i.just.wrote.docs''.		6. Write a commit message like ''Write documentation for sugar3.i.just.wrote.docs''.

	7. Listen to whoever reviews your patch.		7. Create a pull request on GitHub, and make sure to add the ''doc'' label while you are making it.

			8. Listen to whoever reviews your patch.

	= Syntax Information =		= Syntax Information =

SAMdroid: /* Syntax Information */ Fix formatting of newlines

2015-11-17T07:10:57Z

Syntax Information: Fix formatting of newlines

← Older revision		Revision as of 03:10, 17 November 2015
Line 76:		Line 76:
	5. '''Proofread'''. Use the 'make_docs.sh' 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_docs.sh' 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.i.just.wrote.docs''.
Line 87:		Line 87:

	Napolean quick intro: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/		Napolean quick intro: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/

	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 go X in sphinx?: I'm too lazy to find docs. Just duckduckgo or google "sphinx X" if you haven't already.

SAMdroid: Write the first version this page.

2015-11-17T07:09:12Z

Write the first version this page.

New page

This will guide your through how to write docs for a module in sugar3. There are 5 easy steps to writing the documentation, and 2 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

= 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)

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:

<pre>'''
The combobox module provides a combo box; a button like widget which
creates a list popup when clicked. It's best used outside of a
toolbar when the user needs to choose from a *short* list of items.

Example:

.. literalinclude:: ../examples/combobox.py
'''</pre>

3. Document each class. Write a blurb about what the class does and where to use it. If the constructor takes any parameters, or if the class has any signals, they need to be documented here. Place this directly after the class definition. For example:

<pre>class PaletteMenuItem(Gtk.EventBox):
'''
A palette menu item is a line of text, and optionally an icon, that the
user can activate.

The `activate` signal is usually emitted when the item is clicked. It has
no arguments. When a menu item is activated, the palette is also closed.

Args:
text_label (str): a text to display in the menu

icon_name (str): the name of a sugar icon to be displayed. Takse
precedence over file_name

text_maxlen (int): the desired maximum width of the label, in
characters. By default set to 60 chars

xo_color (:class:`sugar.graphics.XoColor`): the color to be applied to
the icon

file_name (str): the path to a svg file used as icon

accelerator (str): a text used to display the keyboard shortcut
associated to the menu
'''</pre>

4. Document the class methods and global functions. You should document what the method/function does and any side effects that it has. If it takes arguments, the they must have their types and function documented. Same goes for return value. This should be placed after the definition. For example (the following are 2 separate methods from different classes):

<pre> def set_image(self, icon):
'''
Sets the icon widget. Usually this will be a
:class:`sugar3.graphics.icon.Icon`.

Args:
icon (:class:`Gtk.Widget`): icon widget
'''
self._hbox.pack_start(icon, expand=False, fill=False,
padding=style.DEFAULT_PADDING)
self._hbox.reorder_child(icon, 0)</pre>
<pre> def get_value(self):
'''
The value of the currently selected item; the same as the `value`
argument that was passed to the `append_item` func.

Returns:
object, value of selected item
'''
row = self.get_active_item()
if not row:
return None
return row[0]</pre>

5. '''Proofread'''. Use the 'make_docs.sh' 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 :)

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

7. Listen to whoever reviews your patch.

= Syntax Information =

The docgen uses sphinx. Sphinx uses reStructuredText as a markup. We then use autodoc and napoleon to write docstrings using google style.

Napolean quick intro: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/
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.