Documentation Generation

I've just coded up a documentation generator that can take the OpenGL man pages in DocBook format and turn them into (X)HTML.  We were previously using the DocbookXSL stuff, but unfortunately that takes hours and hours to process the OpenGL manual set.  With lxml.etree and fairly straightforward coding I can produce the base documentation in about 20 seconds now.

I've got the Python signatures showing for regular ctypes functions and wrapper objects, but not yet for the custom-written wrappers.  Don't have any wrapper-specific information yet.  There's still rough edges wrt e.g. what Python methods are related to which C methods (the Python methods occassionally show up under two C methods).  Still, you can browse and read the man pages with hyper-linking and reasonable appearance.

The mathml is getting included in the final document, but it doesn't seem to properly render on my Firefox 3.0.1, I gather there's some xsl stylesheets necessary to make it look pretty.  Will have to track those down.  Need to get the links-to-Open-Source samples re-created and then need to look at PyOpenGL-specific documentation sections.  Not tonight, though.


  1. Autumn Cuellar

    Autumn Cuellar on 08/18/2008 10:49 a.m. #

    You shouldn't need to use the XSL scripts to get the MathML to render properly on Firefox. In general, you just need to use the correct extension, such as, .xht or .xhtml. These extensions will also enable IE to display the MathML if you have MathPlayer installed (available for free from: If you're using a server-side script to generate the webpage, just make sure that you're serving the page with the correct MIME type.

  2. Mike Fletcher

    Mike Fletcher on 08/19/2008 4:29 p.m. #

    Thanks so much, just changing the extension to .xhtml worked to get the rendering working on Firefox.

Comments are closed.


Pingbacks are closed.