[Mono-docs-list] Proposing a new documentation subsystem

[Mario Sopena Novales]

Hi,

On 25/11/2007, Jonathan Pryor <jonpryor at vt.edu> wrote:
> On Sun, 2007-11-25 at 13:56 +0100, Valentin Sawadski wrote:
> > On Sat, 2007-11-24 at 14:25 -0500, Jonathan Pryor wrote:
> > > On Sat, 2007-11-24 at 16:16 +0100, Valentin Sawadski wrote:
>
> > > Furthermore, monodoc *already* supports 3rd party assemblies -- this is
> > > how Gtk# and Mono.Fuse documentation, among other assemblies, is
> > > integrated into monodoc.
> >
> > I know that monodoc already supports 3rd party assemblies but I was
> > thinking of measures that would enable 3rd party developers also to
> > benefit from the documentation contribution.
> >
> > Which means some that the documentation might contain some kind of url
> > where contributions can be sent to. Apart from the current mono-only
> > contribution.
>
> This sounds easy enough -- extend the .source XML format to include a
> URL to send edits to.  Then the problem "merely" becomes one of
> documenting the transport format/protocol so that others can write
> servers to integrate with monodoc.  I believe the current protocol is
> SOAP based, so that may need to change....
>
> > Another point of which I have been thinking would be to add 3rd party
> > documentation without having to rebuild the browser and all the sources.
>
> That's already possible.  Just add your (.source, .tree, .zip) set of
> files to your $lib/monodoc/sources directory, and restart monodoc.
> You're done.  Again, see how Gtk# and Mono.Fuse do things.
>
> > Someway that users only have to open http://3rdparty.com/docs in the
> > documentation browser and the browser downloads all the documentation
> > and integrates them into the database backend.
>
> This is a slightly different problem.  It should also be solvable by
> having the concept of a "local" sources directory in addition to the
> system sources directory, e.g. ~/.local/share/monodoc/sources/, nd have
> the local directory read before the system directory.  Again, solvable
> (though I don't know how difficult this would be).

I spoke with Lluis Sanchez about using Mono.Addins to extend the
documentation system and it seems a good approach because we will get
all the subsytem for documentation updates and managment (both for
providers and for doc sources) for free.

This will enable downloading new docs or providers without updating
the whole monodoc system. We can also get rid of the several xml files
needed to finally reach the documentation files and free monodoc
subsytem of some managment code.

Once I have something workable I will post here for further discussion.

Mario