LWN Weekly Edition
Front pageSecurity
Kernel development
Distributions
Development
Announcements
->One big page
This page
Previous weekFollowing week
| |||||||||||||
DevelopmentComing soon: Sphinx 1.0Your editor, naturally enough, has a certain interest in systems designed for the documentation of code and other programming-related topics. The perfect system is hard to find. Word processors tend to just get in the way; they put the focus on appearance instead of content, and the result is hard to process with automated tools. Text-oriented systems tend to work better, but one need only write a book chapter or two in <?DocBook?> before even Emacs-strengthened little fingers collapse under the strain. TeX is a great tool, but, as your editor's dog-eared copy of the TeXbook will attest, attaining (and maintaining) the proper level of TeXpertise requires a non-trivial commitment of time. So the search for better alternatives goes on. In this context, your editor recently stumbled across Sphinx, which is headed toward a 1.0 release one of these days.Sphinx was originally created for use in the generation of the Python documentation, but it has grown to the point that quite a few other projects (including Bazaar, Blender, Calibre, Django, Mayavi, etc) are using it as well. It remains heavily oriented toward code documentation, and it has a number of features (such as extracting documentation strings from functions) to support that goal, but it's not limited to that role. At the core of Sphinx is the reStructuredText markup language. It's a simple language, aimed at minimizing excessive decoration and making the source look as much like the final product as possible. So paragraphs are delineated by blank lines, *italics* becomes italics, bulleted list items begin with asterisks, etc. It's a straightforward, low-ceremony way of getting the text into the system. What Sphinx has done, though, is to add a long list of features and directives on top of reStructuredText. Much of it is intended to make code documentation easy; for example, a C function would be introduced with:
.. cfunction:: void kthread_bind(struct task_struct *k, unsigned int cpu);
When the documentation is generated, this code will be marked up as desired (Pygments is used for that task) and incorporated into the document. Similar directives exist for the documentation of variables, exceptions, classes, methods, command-line options, and so on. Beyond that, there are a number of features intended to help the creation of extensive, multi-volume documents. Sphinx can generate tables of contents which span multiple documents. Index entries will automatically be made from function definitions, but there's a mechanism for adding manual index entries as well. Code examples can be included directly from source files - an invaluable feature for anybody trying to keep documentation and code in sync. There is also an extension mechanism allowing projects to add any special directives they may need. Sphinx can generate output in HTML format or in PDF by way of either LaTeX or rst2pdf. There is a theme mechanism allowing the customization of the output, which generally looks pretty nice, if perhaps just a little on the gaudy side. The current version is 0.6.7, which was released in early June. The development version is 1.0b2, as of this writing. The headline feature for 1.0 appears to be "domains," which provide collections of directives for specific programming languages. Domains, in other words, are another step in turning Sphinx from a Python-specific tool into something more generally applicable. Another important new feature is a builder which can output documents in the Epub format for mobile reader devices. Some new themes have been added. There's quite a bit more; see the release notes for details. While 1.0 is still in development, a look through the discussions on the project's mailing list suggests that quite a few people are using it. This article, clearly, is a superficial overview. To truly describe the ups and downs of a tool like Sphinx would require writing a book with it - something your editor was unable to find the time to do by the weekly LWN deadline. There are larger projects currently under consideration, though, and Sphinx is very much on the radar for those. Any tool which makes the creation of high-quality documentation easier can only be a good thing.
Brief items Quotes of the week
Naturally I searched for a font editor, and the best one I found
was Font Forge, an old Linux app ported to the Mac but still
requiring X11. So that's two ways OS X is borrowing from Linux for
font support. What's up with that? Was there an elite cadre of
fontistas working on Linux machines in a secret bunker? Linux is,
um, not usually known for its great designers.
-- Robey
Pointer
Write a compiler, not an interpreter, for in an interpreter, you
will always find an easy way to cheat yourself out of the
labyrinth, and you will never have to face the cold, hard walls of
reality and triumph over the Minotaur.
-- Manuel
Simoni
Don't be a slave to syntax. Syntax is the Maya of programming, forever blinding many of the weaker souls to the eternal light of symbolic expressions.
Thrilled to read that Intel finally did the right thing, and
dropped the requirement for (C) assignment (of whatever form) to
be able to contribute to clutter - making it a truly open project;
nice! I feel a sudden urge to contribute, something, anything now
it belongs to us all.
-- Michael
Meeks
The Eclipse Helios "release train"The Eclipse project has announced the arrival of its annual "release train," called Helios. "The Helios release is the largest release train produced by the Eclipse community, including 39 different project teams, over 33 million lines of code and the work of 490 committers. The release train makes it easier for users and adopters of Eclipse technology to adopt new versions of Eclipse projects." New features include a new Linux development environment, Git support, and more.
F-Spot 0.7.0 releasedThe F-Spot 0.7.0 release kicks off a new development cycle for this photo management application. "The goal of thus cycle is to replace as much code bits by Banshee-code (where possible), clean up, refactor, blingify. All of this will make it much more stable and hackable, allow us to solve some of our long standing issues (performance / memory usage) and do more radical changes (on the UI and internally)."
Firefox 3.6.4 and Thunderbird 3.0.5Mozilla has released Thunderbird 3.0.5 and Firefox 3.6.4. See the release notes (Thunderbird, Firefox) for details, such as tabbed email in Thunderbird and crash protection in Firefox.
GParted 0.6.0 releasedVersion 0.6.0 of the GParted partition editor is out. The biggest change in this release is support for large-sector drives.
Membase database releasedThe first public beta of the Membase key-value database has been announced. "Membase is a simple, fast and elastic "NoSQL" database technology 100% compatible with memcached, the de facto standard for distributed object caching behind web applications. Optimized for storing the data behind interactive web applications, membase is an extremely low-latency, high-throughput system and delivers highly predictable performance unmatched by any other NoSQL solution."
SeaMonkey 2.0.5 releasedThe SeaMonkey 2.0.5 release is out with another set of security updates; details can be found in the release notes.
Tahoe filesystem v1.7.0 releasedVersion 1.7.0 of the Tahao least-authority filesystem is available. "The major new feature is an SFTP server. This means that (with enough installing software and tinkering with your operating system configuration) you can have a normal-looking mount point backed by a Tahoe-LAFS grid."
VLC 1.1.0 releasedVersion 1.1.0 of the VLC media player is out. New features including GPU-based video decoding, a number of new codecs (including VP8, naturally), a new extension framework, performance improvements, and more. The changelog has the details.
Newsletters and articles Development newsletters from the last week
Google releases command line tool for accessing Web services (ars technica)Ars technica looks at GoogleCL, a command line tool for Google web services. "GoogleCL was developed in Python on top of the gdata-python-client library. It's an open-source software project that's hosted on Google Code and distributed under the Apache license. Users who want to contribute fixes and improvements can submit patches through the project's issue tracker."
Piël: ZeroMQ an introductionNicholas Piël has posted an introductory description of the ZeroMQ messaging system. "The API is deceptively simple, and it makes sending messages really simple compared with a raw socket implementation where you have to continuously 'feed' the socket buffer. In ZeroMQ you can just fire off an async send call, it will queue the message in a separate thread and do all the work for you. Because of this async nature, your application does not have to waste time waiting until the message has been flushed. The async nature of 0MQ makes it a perfect companion for an event-based framework." LWN also looked at 0MQ back in January.
Page editor: Jonathan Corbet |
|||||||||||||