1,285
edits
Changes
→Example Docstring
* Targeted release: 0.108
* Targeted release: 0.108
* Last updated: 8/Aug
* Last updated: 8/Aug
* Percentage of completion: 10%
* Percentage of completion: 10% (see [https://developer.sugarlabs.org/sugar3/ documentation website])
== Detailed Description ==
== Detailed Description ==
* Create a sphinx configuration file so we can have a website (DONE)
* Create a sphinx configuration file so we can have a website (DONE)
* Translate existing docs into 1 consistent style
* Translate existing docs into 1 consistent style
* Write docs for all other public ''sugar3'' classes
* Write docs for all other public ''sugar3'' classes, see [[/How To Write]]
=== Example Docstring ===
Let's just use google style doc strings, they are very clean and similar to the current style. [http://sphinx-doc.org/ext/example_google.html#example-google Longer example.]
<nowiki>
# GPLv3...
'''
The module does something which should be summarised here.
Example:
Something representitive of the overall module::
from example import ClassyClass
# Explain non-obvious behaviour
c = ClassyClass(a=1, b=2)
c.props.c = 3
c.thing()
STABLE.
'''
from gi.repository import GObject
class ClassyClass(GObject.GObject):
'''
The ClassyClass does blah, blah. Explain common usage pattern of
this class, such as calling the `thing` function to do a thing.
The `lol` signal is emitted when the class is laughing or when a
different non-obvious condition happens.
Args:
a (int): description of a
b (int): b could be a contrustor argument or a GObject props
that you can invoke using the **kwargs
c (int): desctiption of c
d (:class:`sugar3.graphics.alert.Alert`): remember to link
classes using the correct syntax
.. code-block:: python
c = ClassyClass()
# This is just an example of using this class
'''
def __init__(self, **kwargs):
GObject.GObject.__init__(self, **kwargs)
def thing(self, happy, lol=False):
'''
What a description for this function!
Args:
happy (bool): a description for happy
Keyword Arguments:
lol (bool): a optional argument, explain what
it defaults to
Returns:
type: explaintaion
'''
pass
</nowiki>
== Benefit to Sugar ==
== Benefit to Sugar ==
== Release Notes ==
== Release Notes ==
The Sugar toolkit now has imporved API documentation coverage. View our docs here: dev.sam.today (real url when it is done of course)
The Sugar Toolkit has improved API documentation. See https://developer.sugarlabs.org/sugar3/
== Comments and Discussion ==
== Comments and Discussion ==