Re: New AutoDoc Module planned

[Dan Haywood <da...@haywood-associates.co.uk>]

Hi Martin,

Sorry not to reply before now.  I've cc:'d my reply to the users@isis.a.o
list because it may well be of interest to others.

So, thoughts on autodoc...

First, this probably wants to be a build process; so you could look at our
isis-maven-plugin; that spins up the entire runtime.  You could then write
a service like the MetaModelService; it has an export() method that
iterates over the entire domain model.

As you know I'm a fan of asciidoc(tor), what I like about Asciidoctor is
that you can embed plantuml class, sequence, component diagrams... if you
download AsciidocFX you'll see how easy it is to do.

So for static content you could have an AsciidocFacetFactory and
AsciidocFacet thatlooks for a supplemental .adoc file (eg Customer.adoc)
and attached to the ObjectSpecification.  The maven plugin would then
search for all objectSpecs with this facet and assemble the .adoc text;
these could then be processed by the asciidoctor-maven-plugin... it could
use the template that we use for the Isis docs, or some other template as
you wish.  (BTW, a separate usage of such an AsciidocFacet might be to
provide a help page as an overlay within the wicket viewer).

One thing I'm not sure about is how to create a hierarchy/structure fo the
resultant document, perhaps it's physical, following the package names, or
perhaps it's logical, by reading the ObjectSpecIdFacet ... this will return
the value of @DomainObject(objectType="customers.Customer"), basically an
alias for the class' type.

For dynamic content, if you are using the wrapper factory for the
participants in your code, then you could use a callback to be able to
generate plantuml sequence diagrams, these could then be assembled
together.  As a first cut you would only get to see the interactions for
those obejcts that are already wrapped (I know that Oscar Bou does this as
a matter of course, but most people don't, I think).  One might require
implementing (as an optional feature within Isis itself) some sort of
autowrap capability for whenever a service is injected or is returned from
a service.

Hope those ideas are useful.

Cheers
Dan







On Mon, 23 Jan 2017 at 02:09 Martin Hesse <mw...@gmail.com> wrote:

> Hi Dan,
>
> I have to write user documentation for an application I created with
> Apache Isis. I thought the best way to go about this would be to generate
> the main part of the documentation from the UI model. I was looking through
> the code a bit but didn't find the obvious Service that I could use for
> that. I would like to access an object graph that describes the application
> from a UI perspective so that I can inject this into a series of templates
> and output some document describing the menu actions and the entities and
> so on. I planned to release this as a new addon module.
> Would be very thankful for a few advice where to start looking or how to
> approach the problem best :-)
>
> Thanks and regards,
> Martin
>
>
>
>
>
> --
> Martin Hesse
>
> T: +66 988 32 68 44
> e: mwhesse@gmail.com
>
>