Difference between revisions of "Features/Sugar3 Docs"

From Sugar Labs
Jump to navigation Jump to search
(Created page with ". == Summary == Add developer API documentation to sugar-toolkit-gtk3 in a consistent format. Then, create a site to make the docs available in your bro...")
 
 
(8 intermediate revisions by 3 users not shown)
Line 11: Line 11:
 
* 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 ==
Line 41: Line 108:
  
 
== 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 ==

Latest revision as of 01:01, 3 January 2017


Summary

Add developer API documentation to sugar-toolkit-gtk3 in a consistent format. Then, create a site to make the docs available in your browser.

Owner

  • Name: Sam P.
  • Email: @sam.today

Current status

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, see /How To Write

Example Docstring

Let's just use google style doc strings, they are very clean and similar to the current style. Longer example. 

# 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

Benefit to Sugar

This will allow developers to create activities more eaisly. They will no longer have to look thought the source code th understand how the api works, they will instead (hopefully) have understandable docs with good working code samples.

Scope

This will require lots of changes in the docstrings. However, no changes will be made to code that runs on users machines.

UI Design

Example docs: http://dev.sam.today/ http://dev.sam.today/sugar3.graphics.alert/ http://dev.sam.today/sugar3.graphics.animator/

How To Test

  • View docs
  • Try code samples

User Experience

None for sugar users.

Dependencies

None

Contingency Plan

None

Release Notes

The Sugar Toolkit has improved API documentation. See https://developer.sugarlabs.org/sugar3/

Comments and Discussion

Retrieved from "https://wiki.sugarlabs.org/index.php?title=Features/Sugar3_Docs&oldid=99859"