Weekly Edition
Return to the Development page
| |||||||||||||
Introducing Sphinx, the Python documentation toolchainThe first public release of the Python Sphinx documentation system, which should not be confused with the CMU Sphinx speech recognition project, has been announced. ![[Python Sphinx]](/images/ns/PythonSphinxlogo.png)
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects, written by Georg Brandl and licensed under the BSD license.
It was originally created to translate the new Python documentation, but has now been cleaned up in the hope that it will be useful to many other projects. (Of course, this site is also created from reStructuredText
sources using Sphinx!)
The Sphinx introduction states: "The focus is on hand-written documentation, rather than auto-generated API docs. Though there is limited support for that kind of docs as well (which is intended to be freely mixed with hand-written content), if you need pure API docs have a look at Epydoc, which also understands reST." An interesting feature of the Sphinx web pages is the inclusion of their own document source code. The document source code from the previously mentioned Sphinx introduction page is a good place to go to get a look at the reStructuredText language that Sphinx uses. More information on that language can be found in the A ReStructuredText Primer, the Quick reStructuredText user reference and the reStructuredText Cheat Sheet. The Sphinx feature list includes:
The Python source code and related files for Sphinx are available for download here. The change log shows that a number of recent releases have been made. As of this writing, the current version is release 0.1.61950, dated March 26, 2008. If you need to maintain a collection of web-based or print-based project documentation, Sphinx could be a very useful tool. (Log in to post comments)
Introducing Sphinx, the Python documentation toolchain Posted Mar 27, 2008 6:33 UTC (Thu) by jhs (guest, #12429) [Link] Well, this article inspired me to clean up my Tomboy note and post a document all about Sphinx templating. At the moment, the Sphinx documentation does not cover customizing your templates, which is probably something most people want to do. So I read the source and wrote up that post. It also covers things like CSS and a few How-To walkthroughs.
Introducing Sphinx, the Python documentation toolchain Posted Mar 27, 2008 11:33 UTC (Thu) by amk (subscriber, #19) [Link] Minor correction: Pygments can syntax-colour many different programming languages, not just Python.
How many sphinx can you get? Posted Mar 27, 2008 15:04 UTC (Thu) by melo@simplicidade.org (guest, #4380) [Link] Another one? :) http://www.sphinxsearch.com/ But the project is cool. I wonder if we can use it with other languages?
How many sphinx can you get? Posted Mar 27, 2008 18:38 UTC (Thu) by jhs (guest, #12429) [Link] Yes there are already a few Sphinx projects out there. Oh well. About other languages, Sphinx is not an API documenter like Doxygen or Javadoc or whatever. It is more for the hand-written stuff like introductions, walkthroughs, HOWTOs, etc. Since Pygments can do syntax hilighting for many languages, Sphinx is definitely worth an investigation for your own project. Composing in restructured text format is very easy and intuitive, and the HTML and PDF (via LaTeX) output Sphinx gives you is very nice.
Introducing Sphinx, the Python documentation toolchain Posted Mar 31, 2008 10:47 UTC (Mon) by liljencrantz (subscriber, #28458) [Link] I wish this article had given a better description of why this tool is more suitable for hand written non-api documentation than simply using a tool like Doxygen. With Doxygen, it is simple enough to write simple text in a tex-like mini-language, which contains links (and auto-linking), divides the text into multiple pages, supports styling and templates, supports generating man pages, html output, windows help files, pdfs and various other formats, etc.. I suspect Spinx makes some things easier to do than using Doxygen, but this article does not make it clear when and how it does so.
|
|||||||||||||