[BangPypers] Python doc using sphinx

[Vaidik Kapoor]

Vineet pretty much told you what you have to do. And that's actually pretty
much it. sphinx-quickstart is pretty helpful as well to get you smoothly
started with things.

Now a couple of things from my experience of documentation and Sphinx:

   1. A very general advice. Keep writing docs as you write code. And I am
   not talking about inline code documentation but what goes in your official
   auto generated docs. It will be just a lot less work to do as compared to
   doing it all at once. Also, Sphinx uses RST and has some of its own flavour
   to it. Getting started early with writing Sphinx docs will just help you
   use those flavours better as they are pretty useful for auto-generating
   docs (things like referencing classes, functions and modules in the
   documentation which Sphinx converts into proper hyperlinks while generating
   docs).
   2. One feature of Sphinx that I find very useful is the USAGE directive
   (look it up in the docs). It helps you show with the help of an example in
   docstring as to how a class, function, mod, etc. can be used. If I am not
   wrong, Sphinx also provides a way to test these little code-snippets to
   make sure that they are not wrong. Check out Flask's or Wekrzeug's Makefile
   to see how the Pocoo team does docs testing.
   3. Do something about maintaining docs versions automatically. Changing
   versions seems to be the most painful thing IMO, especially if you have to
   do it at a multiple places - you just can't remember all. How I have done
   for one of my projects [1]. But sometime this may work and sometime it
   might be a pain to do this. Another easy way could be that you use a
   Makefile to change the version string in the docs conf.py file. But all
   this hard work really matters if your project is going to get frequent
   changes and updates.
   4. Be prepared. It is still going to be a lot of work, especially if you
   are not used to writing docs. But it will give you an amazing sense of
   achievement as it will help the people who you are writing it for.

[1]: https://github.com/vaidik/incoming/blob/master/docs/conf.py#L58

Vaidik Kapoor
vaidikkapoor.info


On 26 May 2014 10:08, Vineet Naik <naikvin at gmail.com> wrote:

> 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
> _______________________________________________
> BangPypers mailing list
> BangPypers at python.org
> https://mail.python.org/mailman/listinfo/bangpypers
>