Features/Sugar3 Docs: Difference between revisions

Retrieved from "https://wiki.sugarlabs.org/go/Features/Sugar3_Docs"

@@ Line 11: / Line 11: @@
 * Targeted release: 0.108
 * Last updated: 8/Aug
-* Percentage of completion: 10%
+* Percentage of completion: 10% (see [https://developer.sugarlabs.org/sugar3/ documentation website])
 == Detailed Description ==
 * Create a sphinx configuration file so we can have a website (DONE)
 * 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 ==
@@ Line 41: / Line 108: @@
 == 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 ==