[Mono-docs-list] monodoc --edit crashes on newly created doc

[Jonathan Pryor]

On Sun, 2010-02-21 at 14:28 -0500, Matthew Pirocchi wrote:
> I'm working on following this guide to getting started on documenting
> my code:
> http://www.mono-project.com/Generating_Documentation
> 
> 
> My code is divided into 4 assemblies, so I generated the documentation
> with these 4 commands:
> 
> 
> mdoc update -o cardinal-doc Cardinal.exe
> mdoc update -o cardinal-doc Cardinal.Core.dll
> mdoc update -o cardinal-doc Cardinal.Interface.dll
> mdoc update -o cardinal-doc Cardinal.Services.dll

Don't do that.

'cardinal-doc/index.xml' is supposed to contain all the types that are
within the assemblies you're documenting.  However, it is regenerated
each time 'mdoc' runs, and contains only those assemblies which are
being processed for that invocation.

Result: your second 'mdoc update' command causes index.xml to "lose" all
the types that were added by the first 'mdoc update', and the third
overwrites the second invocation, and...

There are two ways to handle multiple assemblies:

1. List all the assemblies at the same time, thus allowing index.xml to
properly contain all the types within the documentation index:

        mdoc update -o cardinal-doc Cardinal.exe Cardinal.Core.dll \
        	 Cardinal.Interfaces.dll Cardinal.Services.dll

2. Have multiple mdoc repositories, one per assembly:

        mdoc update -o cardinal-docs/Cardinal Cardinal.exe
        mdoc update -o cardinal-docs/Cardinal.Core Cardinal.Core.dll
        # ...

I follow (2) within http://gitorious.org/cadenza, placing documentation
within 'src/ASSEMBLY/Documentation/en', e.g. my MSBuild file [0]
contains a post-build event which updates the documentation [1]:

        <Import Project="..\..\lib\mdoc-net\mdoc.targets" />
        <PostBuildEvent>
                $(Mdoc) update --exceptions=added -o $(ProjectDir)Documentation\en $(TargetPath)
        </PostBuildEvent>

mdoc-export-html will accept multiple source directories, allowing a
single directory tree to contain documentation from all the assemblies:

        mdoc export-html -o html src/*/Documentation/en

To use 'monodoc --edit', you would need to use --edit separately for
each directory:

        monodoc --edit cardinal-docs/Cardinal \
        	--edit cardinal-docs/Cardinal.Core \
        # ...
> MonoDoc opens, and I see "Cardinal" in the sidebar as expected. I can
> click on "Cardinal", but when I expand it and try to click on any of
> its assemblies, monodoc crashes with this trace:

Which version of Mono is this?  Mono 2.4 seems to crash a lot for me,
while 2.6 and/or trunk seem far more stable.  I haven't investigated
why.  This could be the cause of your current pains, or having a
"confused" index.xml (as described above) could be the cause as well.

 - Jon

[0]
http://gitorious.org/cadenza/cadenza/blobs/master/src/Cadenza/Cadenza.csproj

[1]
http://gitorious.org/cadenza/cadenza/trees/master/src/Cadenza/Documentation/en