On Fri, Feb 18, 2011 at 5:00 AM, Burhan <burhan.kha...@gmail.com> wrote: > Hello: > > I am new to Sphinx, and am going to use it for a python project to > generate HTML documentation. My problem is rather basic, I'm not sure > how to format my docstrings so that Sphinx can extract the > information. > > I understand about using autodoc extension, and making sure that my > modules are available to python so that sphinx can find my code - my > problem is a bit basic, how do I actually comment the code? > > Do I have to enter *verbatim* examples are written in the > documentation? So for example, is it like this: > > def my_funct(param=None,param2=None): > """ > .. py:func:: my_funct(param=None,param2=None) > This function does something with two parameters, > which are default to :py:`None` > """ > > Or do I have to document it separately in another file? A simple > python code example would really help me out. > > Thanks. > > -- > You received this message because you are subscribed to the Google Groups > "sphinx-dev" group. > To post to this group, send email to sphinx-dev@googlegroups.com. > To unsubscribe from this group, send email to > sphinx-dev+unsubscr...@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/sphinx-dev?hl=en. > >
The basic idea is that you just use "info field lists" (http://sphinx.pocoo.org/domains.html?highlight=info%20field%20lists#info-field-lists) to document function parameters directly in your docstrings. If you need more details, I wrote a fairly simple PyQt app called MDIImageViewer and one of its goals was to demonstrate how to document Python projects using Sphinx. You can find the generated HTML documentation at: http://tpgit.github.com/MDIImageViewer. Clicking on the "Show Source" link on any page will show you the Sphinx .rst source for that page. http://tpgit.github.com/MDIImageViewer/implementation.html#sphinx-documentation-notes briefly discusses how I used Sphinx to generate the documentation. The Python sources are at: http://github.com/tpgit/MDIImageViewer/archives/master, The Sphinx .rst files are at http://github.com/tpgit/MDIImageViewer/tree/master/sphinx/. For one example of how to document a Python method see http://tpgit.github.com/MDIImageViewer/imageviewer.html#imageviewer.ImageViewer.scaleImage. Click on the [source] link on the right to see the actual Python method (along with its docstring that generated the documentation). -- TP -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
