This is awesome. I have never expected that someone has such a thing that ready now :) Awesome. I am still in a shock.
[phpdoc included for discussions].
I've been tinkering with something that I call "livedocs"; instead of generating everything in one pass, it indexes the phpdoc sources and stores information about the entities and node ids (eg: refsect1="function.fopen"), and in which files they can be found.
This process takes about 2 minutes (storing information into an sqlite database ;-)
Hm, sqlite again :)
Once done, you can call up the docs for a given node id and it will transform the XML to clean HTML on the fly (using ext/xml and a couple of queries to the sqlite database) - it transforms only the file that you requested, so the process is quite fast.
I would be very happy to see that code. Is that some custom SAX PHP code?
The main goals I had in mind were: 1.) I didn't want to wait 45 minutes for the build when I wanted to preview doc changes. 2.) I wanted to maintain a local, up-to-date copy of the docs, without having to run the build. 3.) I wanted fast access to the docs for a particular function (something like the unix man command), and wasn't particularly interested in the other functions in the same section.
This makes it very easy for people maintaining the docs to focus on the content rather than what they want to spend the next 45 minutes or more doing while waiting to see if their changes look right :).
Yep.
It currently makes no attempt at section/example/figure numbering, nor at generating a TOC.
As numbering goes, the current DSSSL sheets number the examples per page, so it would be very easy to implement here.
You can see an example of a generated page at http://www.php.net/~wez/fopen.html
Great. Looks very great. Except that I don't like how the parameter list is colored at the top, but that would be an easy fix ;)
When I get a little more time, I'll clean it up so that it can handle multiple languages and so on.
It might be feasible to deploy this for the online documentation if we use some kind of content caching (or the 404 trick, as Rasmus calls it :).
I think we can build an XML version of the TOC very easily with XSLT. There is code for this to build some custom HTML code, which can be easily modified to create some XML format instead. Then that can be stored in the DB to show when needed. Or that can be parsed with PHP [I thought about this method].
It might also be the case that generating the docs in advance with this code might be significantly faster than the regular dsssl or xsltproc builds, as the transformation is quite simple; need to do some benchmarks.
It would be nice to see some benchmarks.
I must also point out that this project is also a great forerunner to implement my proposal of the self hosted documentation, which can work from XML sources this way, which would speed up deployment and updates. So it is a great time to see this development. I planned to write some proof of concept version of that self hosted documentation for the linuxtag docmeeting. It would be nice to include your improvements in that. :)
Goba
-- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
