Roger Binns schrieb: > 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.
Yes, that's unfortunate. About the packages; I tried to only use packages that should be present in modern TeX distributions. > 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. Yes, documentation on extensions is somewhat lacking. I thought that looking at the existing directives and roles would be better than most documentation anyway. If you know some place where a quick hint would help, please tell! > 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. I don't know the exact reason for this either; it's some internal docutils thing. > 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. And I'm very thankful that you have contributed so much in terms of suggestions and questions! cheers, Georg --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
