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 <naik...@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 < > kracethekingma...@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.n...@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@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@python.org > > https://mail.python.org/mailman/listinfo/bangpypers > > > > > > -- > ~ Vineet > _______________________________________________ > BangPypers mailing list > BangPypers@python.org > https://mail.python.org/mailman/listinfo/bangpypers > _______________________________________________ BangPypers mailing list BangPypers@python.org https://mail.python.org/mailman/listinfo/bangpypers
