1 / 32

Creating Robust Documentation with Sphinx and Doctests

Creating Robust Documentation with Sphinx and Doctests. Christopher Perkins PyWork November 2008. What is Sphinx?. Auto Generated Docs. Developer Modifiable. But doesn't epydocs do that?. Yikes!. Multiple Output Formats. LaTeX. PDF. HTML?. reStructured Text. Developer Driven.

robbin
Download Presentation

Creating Robust Documentation with Sphinx and Doctests

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Creating Robust Documentation with Sphinx and Doctests Christopher Perkins PyWork November 2008

  2. What is Sphinx?

  3. Auto Generated Docs

  4. Developer Modifiable

  5. But doesn't epydocs do that?

  6. Yikes!

  7. Multiple Output Formats LaTeX PDF HTML?

  8. reStructured Text

  9. Developer Driven

  10. Why do you need more than docstrings?

  11. Naratives http://www.flickr.com/photos/josephhoetzl/2537201140/

  12. Tutorials http://farm4.static.flickr.com/3258/2725759719_c49318962e.jpg?v=0

  13. Integrate http://www.flickr.com/photos/happymonkey/2325420169/

  14. Restructured Text

  15. Paragraphs in ReST I am a paragraph. Hey! Look down here, another paragraph. Notice the line between me and my brother above.

  16. Lists • I am the first item in the list • I am part of an inner list • I am also in the inner list • I make this look easy. • Roman Numerals also work. • Makes me look like I’m a college thesis or something.

  17. Headings Chapter 1 Title =============== Section 1.1 Title ----------------- Subsection 1.1.1 Title ~~~~~~~~~~~~~~~~~~~~~~ Section 1.2 Title ---------------- * The underline has to be the length of the text…

  18. Restructured Text Tables +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+

  19. Etc. • Links Python_ is `my favorite programming language`__. .. _Python: http://www.python.org/ __ Python_ • Images .. image:: images/ball1.gif

  20. ReST Directives • Looks like: .. directive_name: : directive data • Sphinx defines a number of directives. • Provide your own directives with Sphinx extensions.

  21. First Demo

  22. So? What else?

  23. Searchable http://www.flickr.com/photos/peteashton/22934348/

  24. Customization

  25. Pygments Syntax Highlighting • MuPad • OCaml • PHP • Perl • Python (incl. console sessions and tracebacks) • Redcode • Ruby (incl. irb sessions) • Scheme • Visual Basic.NET • and more! • Delphi • Dylan • Erlang • Haskell (incl. Literate Haskell) • Java • JavaScript • Lua • MiniD • MooCode • ActionScript • Assembly (various) • Boo • Befunge • BrainFuck • C, C++ • C# • Common Lisp • D

  26. Testing Integration Courtesy: XKCD

  27. Did you say Doctests?

  28. Test Discovery (using Nose)

  29. Doctest Demo Here

  30. In Summary. • Documentation is important. • Documentation should be correct. • Not enough docs in OSS. • If it's good enough for Guido...

  31. References • Tutorial: pythontutorials.googlecode.com • Me: www.percious.com • Video Presentation: search sphinx at www.showmedo.com • Sphinx: sphinx.pocoo.org • XKCD: http://blag.xkcd.com/

More Related