[Mono-dev] Mono.Addins in Monodoc

[Lluis Sanchez]

Hi,

For some time I've been thinking about changes required in Monodoc,
especially regarding how Monodoc creates the documentation tree and
locates the available documentation. I'm posting my ideas here because
Mike told me that he is going to spend some time fixing Monodoc, so
maybe those ideas are a good starting point for the changes to be made.

My idea is to use Mono.Addins to handle all extensibility of Monodoc.
There would be at least two extension points:

      * Documentation providers: classes implementing the Provider
        class: ecma, man, error, etc. Some abstraction work will be
        needed, since Provider and HelpSource object creation is
        hard-coded right now. 
      * Documentation sources: New document nodes to show in the
        documentation tree. It would replace the existing monodoc.xml
        file and the sources subdir.

The use of add-ins for registering new documentation sources probably
requires some more explanation. Here is an example of how the extension
point might look like:

<Addin id="Core" namespace="Monodoc" version="2.0" isroot="true">
	<!-- Declaration of the extension point for help sources -->
	<ExtensionPoint path="/Monodoc/HelpSources">
		<ExtensionNode name="Node" type="Monodoc.Node" />
	</ExtensionPoint>
	...
	<Extension path="/Monodoc/HelpSources">
		<!-- Some default documentation sources, included in Monodoc -->
		<Node id="classlib" label="Class Library" provider="ecma" file="netdocs" />
		<Node id="classlib-mono" label="Mono Libraries" provider="ecma" file="Mono" />
		<Node id="ecmaspec" label="C# Language Specification" provider="ecmaspec" file="ecma334" />
		<Node id="dev-tools" label="Mono Development Tools" />
		<Node id="various" label="Various">
			<Node id="classlib-nunit" label="NUnit Libraries" provider="ecma" file="nunit-docs" />
		</Node>
	</Extension>
</Addin>

So, given this extension point and that set of nodes defined by Monodoc,
here are some examples of documentation source add-ins:

<!-- Add-in which register MonoDevelop api documentation -->
<Addin id="MonoDevelop" namespace="Monodoc.Sources">
	<Dependencies>
		<Addin id="Core" version="2.0" />
	</Dependencies>
	<Runtime>
		<!-- Files included in the add-in -->
		<Import file="monodevelop-reference.tree" />
		<Import file="monodevelop-reference.zip" />
	</Runtime>
	<Extension path="/Monodoc/HelpSources"> 
		<!-- Registers the new node, specifying the provider and source file -->
		<Node id="monodevelop" label="MonoDevelop API" provider="ecma" file="monodevelop-reference" />
	</Extension>
</Addin>

Notice that add-ins don't need to be implemented in assemblies. An
add-in can just be a set of files. In the example the add-in would be
composed by:

      * Monodoc.Sources.MonoDevelop.addin.xml (with the content above)
      * monodevelop-reference.tree
      * monodevelop-reference-zip


Another example:

<Addin id="MonoProfiler" namespace="Monodoc.Sources">
	<Dependencies>
		<Addin id="Core" version="2.0" />
	</Dependencies>
	<Runtime>
		<Import file="mono-profiler.tree" />
		<Import file="mono-profiler.zip" />
		<Import file="mono-profiler-man.tree" />
		<Import file="mono-profiler-man.zip" />
	</Runtime>
	<Extension path="/Monodoc/HelpSources"> 
		<!-- Registers a new node -->
		<Node id="profiler" label="Mono Profiler API" provider="ecma" file="mono-profiler" />
	</Extension>
	<Extension path="/Monodoc/HelpSources/dev-tools">
		<!-- Register a new child node of dev-tools -->
		<Node id="profiler-tool" label="Mono Profiler" provider="man" file="mono-profiler-man" />
	</Extension>
</Addin>

What's nice about using Mono.Addins for all this?

      * Monodoc can leverage all add-in management functionality that
        Mono.Addins provides. We could setup an online repository with
        documentation add-ins and let the user choose which
        documentation to install.
      * There would be more flexibility about where to put the
        documentation sources. Add-ins can be installed at system level
        or in the user home directory.
      * Documentation sources can include or "pull" the documentation
        providers needed to visualize them. Since all are add-ins, a
        documentation source add-in can declare dependencies on other
        source or provider add-ins.
      * If we share the same add-in space with MonoDevelop, we can
        publish MD add-ins which include documentation. For example, the
        MonoDevelop Boo add-in might include documentation about Boo,
        and that documentation would be visible in Monodoc even if the
        add-in was installed using the MonoDevelop add-in manager.

Lluis.