Caching mdoc's ASP.NET-generated HTML - Jonathan Pryor's web log
« Configuring the ASP.NET front-end for mdoc | Main | Assembly Versioning with mdoc »
Caching mdoc's ASP.NET-generated HTML
Last time we discussed configuring the ASP.NET front-end to display monodoc documentation. The display of extension methods within monodoc and the ASP.NET front-end is fully dynamic. This has it's pros and cons.
On the pro side, if/when you install additional assembled documentatation sources, those sources will be searched for extension methods and they will be shown on all matching types. This is very cool.
On the con side, searching for the extension methods and converting them into HTML takes time -- there is a noticable delay when viewing all members of a type if there are lots of extension methods. On heavily loaded servers, this may be detrimental to overall performance.
If you're running the ASP.NET front-end, you're not regularly adding documentation, and you have Mono 2.6, you can use the mdoc export-html-webdoc command to pre-render the HTML files and cache the results. This will speed up future rendering.
For example, consider the url http://localhost:8080/index.aspx?link=T:System.Collections.Generic.List`1/* (which shows all of the List<T> members). This is a frameset, and the important frame here is http://localhost:8080/monodoc.ashx?link=T:System.Collections.Generic.List`1/* which contains the member listing (which includes extension methods). On my machine, it takes ~2.0s to download this page:
$ time curl -s \ 'http://localhost:8080/monodoc.ashx?link=T:System.Collections.Generic.List`1/*' \ > /dev/null real 0m2.021s user 0m0.003s sys 0m0.002s
In a world where links need to take less than 0.1 seconds to be responsive, this is...pretty bad.
After running mdoc export-html-webdoc netdocs.zip (which contains the List<T> docs):
$ time curl -s \ 'http://localhost:8080/monodoc.ashx?link=T:System.Collections.Generic.List`1/*' \ > /dev/null real 0m0.051s user 0m0.003s sys 0m0.006s
That's nearly 40x faster, and within the 0.1s guideline.
Cache Generation: to generate the cache files, run mdoc export-html-web ASSEMBLED-FILES. ASSEMBLED-FILES consists of the .tree or .zip files which are generated by mdoc assemble and have been installed into $prefix/lib/monodoc/sources:
$ mdoc export-html-webdoc $prefix/lib/monodoc/sources/Demo.zip
(Where $prefix is your Mono installation prefix, e.g. /usr/lib/monodoc/sources/Demo.zip.)
This will create a directory tree within $prefix/lib/monodoc/sources/cache/Demo. Restarting the ASP.NET front-end will allow it to use the cache.
If you don't want to generate the cache in another directory, use the -o=PREFIX option. This is useful if you're updating an existing cache on a live server and you don't want to overwrite/replace the existing cache (it's a live server!) -- generate the cache elsewhere, then move the files when the server is offline.
If you have lots of time on your hands, you could process all assembled documentation with:
$ mdoc export-html-webdoc $prefix/lib/monodoc/sources/*.zip
Limitations: It should be noted that this is full of limitations, so you should only use it if performance is really important. Limitations include:
- The existence of the cache subdirectories are more important than any timestamps; if the .zip file is newer than the corresponding cache directory, the cache contents will still be returned.
- It's privy to monodoc internals, and thus you may need to regenerate all cached documentation whenever you add or remove .zip files. For example, since it can be used to show extension methods, and any set of documentation can contain extension methods, adding or removing assembled documentation files may render the cached output out of date.
- mdoc export-html-webdoc processing is slow. Processing the 2.4KB Demo.zip takes a speedy 1.2s. Processing the 5.8MB netdocs.zip (51MB uncompressed, containing 4810 types with 45267 members, including List<T> documentation) takes an astounding 247m (over 4 hours). The resulting cache/netdocs directory is 316MB.
Next time, we'll cover mdoc's support for assembly versioning.
blog comments powered by Disqus