-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 http://apsw.googlecode.com/svn/publish/index.html
I previously used hand edited HTML. The HTML was nice in that it was a single standalone file (styles etc incorporated within). Some observations and experience: I gave up trying to use PDF. Even getting it working was a pain as it required numerous tex packages for all the various stylesheets. Some of my tables or code samples are quite wide which work fine under HTML but become a mess in PDF. The CHM works *very* nicely. I wrote several scripts to automate parts of the documentation. One part is a long example code file that prints various things along the way. The output looks like this: (I hope to improve the styling a little bit more in the future.) http://apsw.googlecode.com/svn/publish/example.html I extract the API documentation from the source files where they are in comments (using the /** convention). While it would be nice to use the text as the help at the python level (PyDoc_STR), that involves dealing with multi-line strings and preprocessors. IIRC some compilers don't even support constant strings longer than 512 characters. By using my own tool, I can also do things like sort the API members into alphabetical order. It would be nice to get some sort of class overview of members. For example look at http://apsw.googlecode.com/svn/publish/connection.html which has ~26 members. It would be nice if they showed up in the toc on the left. (I can do so by making each member a section but that bloats the main page a lot). Alternatively I could list them in some sort of infobox at the beginning of the class but that would require some sort of horizontal list so that 26 lines of space aren't taken up. I also wrote something that took a list of SQLite apis called and added an automatic cross reference and index. This could probably be done by defining my own roles and blocks and implementing backends for them, but there are no examples of how to do that in the Sphinx doc. There are examples at docutils.sf.net but it isn't immediately apparent how to glue them into Sphinx. Some of the anchors generated aren't very good. For example look at http://apsw.googlecode.com/svn/publish/changes.html where they are named "r1", "id1", "r2", "id2" etc or http://apsw.googlecode.com/svn/publish/benchmarking.html#id2 (id2 should really be "speedtest"). Most of the time the anchors are good. Overall I am very happy with Sphinx. The documentation looks a lot better, the effort to move over wasn't that much and the underlying quality is a lot higher due to such easy cross referencing, the search function and the ease of proof reading. Roger -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAkkd8U0ACgkQmOOfHg372QTJrQCg1RwRF7vCSW2yrbiBJA+6jrLL PqcAnipmLlmi59VLsokagcBWfHqYiiSs =vlZk -----END PGP SIGNATURE----- --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~----------~----~----~----~------~----~------~--~---
