Difference between revisions of "User talk:Humitos/SugarToolkitDocs"
(Created page with "Just a couple of suggestions. Make it a Makefile target and use a better theme like sphinxdoc :) --dnarvaez") |
|||
| (5 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
Just a couple of suggestions. Make it a Makefile target and use a better theme like sphinxdoc :) --dnarvaez | Just a couple of suggestions. Make it a Makefile target and use a better theme like sphinxdoc :) --dnarvaez | ||
| + | |||
| + | == Tool to be used == | ||
| + | |||
| + | * Sphinx | ||
| + | * epydoc | ||
| + | * Doxigen | ||
| + | * <add your tool here> | ||
| + | |||
| + | |||
| + | Sugarlabs already has a sphinx instance, although it is a bit out of date: http://doc.sugarlabs.org/sphinx/ | ||
| + | |||
| + | It also has a epydoc instance: http://doc.sugarlabs.org/epydocs/ (a.k.a api.sugarlabs.org) | ||
| + | |||
| + | I previously kept a Doxygen parsing of the Sugar toolkit, largely because I know how to make nice dependancy graphs with Doxygen. This currently is not hosted anywhere. | ||
| + | |||
| + | In general each documentation tool I have used has a slightly different style for comments to state things like '@param input_item Describes this input" and "@returns A XYZ object if successful; null on failure". So you should decide on the tool to use that can do everything you want before you formally go annotating the code base. | ||
| + | |||
| + | == Workaround == | ||
| + | |||
| + | * Taken from the sugar-devel mailing list | ||
| + | |||
| + | <pre> | ||
| + | My quick and dirty solution for browsable docs are to just hop into the terminal on an XO and type | ||
| + | pydoc -p 8080 and then point Browse to localhost:8080. Now that we have moved to webkit I'm really | ||
| + | tempted to wrap this up as a little webkit activity to get to the dev docs with no geeking around ;) | ||
| + | </pre> | ||
Latest revision as of 12:19, 5 July 2012
Just a couple of suggestions. Make it a Makefile target and use a better theme like sphinxdoc :) --dnarvaez
Tool to be used
- Sphinx
- epydoc
- Doxigen
- <add your tool here>
Sugarlabs already has a sphinx instance, although it is a bit out of date: http://doc.sugarlabs.org/sphinx/
It also has a epydoc instance: http://doc.sugarlabs.org/epydocs/ (a.k.a api.sugarlabs.org)
I previously kept a Doxygen parsing of the Sugar toolkit, largely because I know how to make nice dependancy graphs with Doxygen. This currently is not hosted anywhere.
In general each documentation tool I have used has a slightly different style for comments to state things like '@param input_item Describes this input" and "@returns A XYZ object if successful; null on failure". So you should decide on the tool to use that can do everything you want before you formally go annotating the code base.
Workaround
- Taken from the sugar-devel mailing list
My quick and dirty solution for browsable docs are to just hop into the terminal on an XO and type pydoc -p 8080 and then point Browse to localhost:8080. Now that we have moved to webkit I'm really tempted to wrap this up as a little webkit activity to get to the dev docs with no geeking around ;)