[Mono-dev] Mono.Addins in Monodoc
lluis at ximian.com
Tue Dec 18 11:30:56 EST 2007
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 -->
<ExtensionNode name="Node" type="Monodoc.Node" />
<!-- 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" />
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">
<Addin id="Core" version="2.0" />
<!-- Files included in the add-in -->
<Import file="monodevelop-reference.tree" />
<Import file="monodevelop-reference.zip" />
<!-- Registers the new node, specifying the provider and source file -->
<Node id="monodevelop" label="MonoDevelop API" provider="ecma" file="monodevelop-reference" />
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
* Monodoc.Sources.MonoDevelop.addin.xml (with the content above)
<Addin id="MonoProfiler" namespace="Monodoc.Sources">
<Addin id="Core" version="2.0" />
<Import file="mono-profiler.tree" />
<Import file="mono-profiler.zip" />
<Import file="mono-profiler-man.tree" />
<Import file="mono-profiler-man.zip" />
<!-- Registers a new node -->
<Node id="profiler" label="Mono Profiler API" provider="ecma" file="mono-profiler" />
<!-- Register a new child node of dev-tools -->
<Node id="profiler-tool" label="Mono Profiler" provider="man" file="mono-profiler-man" />
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.
More information about the Mono-devel-list