Upgrade docstring to Sphinx style.

[hupili]

Some original docstring is in Java-style (junbo initialized in doxygen style). We want to change to Sphinx style. First is to conform to Python convention. Second is to help auto documentation.

[hupili]

example of doxygen style:

plugin/renren.py:292:        @param status: StatusID object
plugin/renren.py:293:        @param text: string, the reply message
plugin/renren.py:394:        @param count: number of statuses

[hupili]

example of Sphinx style:

snsbase.py-255-    def parseCode(self, url):
snsbase.py-256-        '''
snsbase.py:257:        .. py:function:: -
snsbase.py-258-
snsbase.py-259-        :param url: 
snsbase.py-260-            contain code and openID

[hupili]

You can check the difference on the automatic documentation:
http://snsapi.ie.cuhk.edu.hk/doc/

doxygen style is not recognized by Sphinx.

[hupili]

The general guideline of docstring, http://www.python.org/dev/peps/pep-0257/

It does not specify what exact formatting is preferred.

[hupili]

This page contains abundant examples of what a Sphinx-style docstring is like. We use the autodoc extension of Sphinx to extract the docstring and format on the website.

http://packages.python.org/an_example_pypi_project/sphinx.html

[uestcmy]

I am ready to change docstring style, but the question is : ONLY the docstring that in 'doxygen style' should be changed OR the docstring that in some other kind style should be changed?I find some comments are not likely to be docstring.
PS. Do every class,method,object need docstring?

[hupili]

@uestcmy , You can start with those docstrings documented in doxygen format and let me merge them. I think giving a trial for the Github workflow is more important. Once done for the first time, you can add other docstrings. You can view some sample pull requests here .

As a longer term plan, I think:

• docstrings in plain format are not an urgent. As long as the output of Sphinx is easy to read, we can leave them there. As is shown in your SinaBlog post, that piece of docstring is not in complete Sphinx format but the output is still readable and understandable. This is unlike doxygen formatted docstring, which does not render readable output. Once you have more time, you can come back to format them in a nicer way.
• Not every class and method need docstring. Generally, "public" methods (which are intended to be invoked by users and upper layer developers) need docstring. In our convention, "private" methods are prefixed with _ or __. You can check more coding convention. Also, if the name is already highly self-explanary, you don't have to add docstring. e.g. those classes in errors.py.
• The urgency for new docstring: 1) classes in "./snsapi/"; 2) classes in "./snsapi/plugin/"; 3) classes in "./snsapi/plugin_trial".

[hupili]

I'm looking into the problem. Note one ref of Rst,

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

[uestcmy]

I try to use pull request, maybe some mistakes exist.
The docstring in the sina.py, just like home_timeline, give us the introduction of the function of the method and the meaning of the parameter.Pease check the style of the changed part,only several lines.

[uestcmy]

Another question is that I cannot render html of docstring in the *.py in app directory ,like "forward" and "mysofa".
Maybe some mistakes exist which resemble the former one.

[hupili]

@uestcmy

If you want to use automodule directive to autodoc those files, they must form a module first. In Python, this is indicated by a __init__.py under one directory. You can upgrade to my latest "doc" branch. __init__.py is added and apps.rst is modified.

[hupili]

One pointer is left in https://github.com/hupili/snsapi/wiki/Coding-convention