[Mono-dev] Using mdoc for internal documentation

[Casey Marshall]

I'm trying to use mdoc, along with the monodoc asp pages and the  
monodoc browser, to deploy some internal API documentation. I'm having  
trouble getting it to produce documentation for all our assemblies  
(80, which will grow to more than 100).

I had been using `monodocer' in previous releases like this:

   for dll in ${BUILT_DLLS}; do
     monodocer -show_exceptions -path:monodoc -import:xmldoc/`basename  
$dll .dll`.xml -assembly:...
   done
   mdoc assemble --out=monodoc/fish monodoc

the final `-assembly:' args to the monodocer call was an -assembly:  
argument for every assembly in BUILT_DLLS, which contained a list of  
all assemblies produced by our build. The build arguments placed all  
the XML documents in a common directory, xmldoc.

Sometime ago, though, it looks like `monodocer' became an alias for  
`mdoc update'. I'm having trouble getting mdoc-update to do the right  
thing.

I tried this, in makefile syntax (DOC_TARGETS is a list of targets doc- 
*, for each project in our tree, and all-* targets build each project):

   docs: $(DOC_TARGETS)
	mdoc assemble --out=monodoc/fish monodoc

   $(DOC_TARGETS): doc-%: all-%
	-mdoc update --out=monodoc --import=xmldoc/`$(shell echo $* |  
tr / .).xml $*/bin/Debug/*.dll

This doesn't seem to work; in particular, lots of classes from the  
assemblies are omitted.

One common error I get from `mdoc update' is:

   mdoc: Could not resolve: foo.dll, Version=XXX, Culture=neutral,  
PublicKeyToken=XXX

for various assemblies that I both specify in the assemblies list on  
the command line, AND are in a directory listed in MONO_PATH.

My question, then, is: what's the right way to do this -- assemble a  
bunch of assemblies and XML documentation files into a  
single .tree/.zip file for monodoc?