[BangPypers] Python doc using sphinx

Vineet Naik naikvin at gmail.com
Mon May 26 06:38:30 CEST 2014


Hi,

Basically there are 3 steps involved in this:

1. Write docstrings in your code using reStructuredText directives and
   field lists that are recognized by Sphinx. See an example here
   [1]. It's a good idea refer to docs of existing libs as Kracekumar
mentioned.

2. Enable the autodoc extension in `conf.py` of the Sphinx source
   project and add the path to the code to sys.path so that it's
   importable by Sphinx.

3. Add autodoc directives such as `.. automodule::`, `.. autoclass::`
   etc. in Sphinx source files wherever you want to include the docs
   for the code. See more[2]


Related: (Please don't mind the self promotion :-))

If you use emacs, check sphinx-doc.el[3] which is an emacs minor mode
that I am working on to generate the docstrings for Python functions and
methods from the formal parameters. See demo in the README on github.


[1]: http://sphinx-doc.org/domains.html#info-field-lists
[2]: http://sphinx-doc.org/ext/autodoc.html
[3]: https://github.com/naiquevin/sphinx-doc.el



On Sun, May 25, 2014 at 11:51 PM, kracekumar ramaraju <
kracethekingmaker at gmail.com> wrote:

> Take a look at existing third party library like requests:
> https://github.com/kennethreitz/requests/tree/master/docs
>
>
> On Sun, May 25, 2014 at 11:43 PM, Nitin Kumar <nitin.nitp at gmail.com>
> wrote:
>
> > I need to document python code under github repo with Sphinx for auto doc
> > generation. Anyone got good tips & tricks, samples?
> > _______________________________________________
> > BangPypers mailing list
> > BangPypers at python.org
> > https://mail.python.org/mailman/listinfo/bangpypers
> >
>
>
>
> --
>
> *Thanks & Regardskracekumar"Talk is cheap, show me the code" -- Linus
> Torvaldshttp://kracekumar.com <http://kracekumar.com>*
> _______________________________________________
> BangPypers mailing list
> BangPypers at python.org
> https://mail.python.org/mailman/listinfo/bangpypers
>



-- 
~ Vineet


More information about the BangPypers mailing list