How to create a site/doxia plugin?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

How to create a site/doxia plugin?

Peter Nabbefeld

Hello,

I haven't ever written a maven plugin. But, as I'm not satisfied with
the doxia plugins available, I'd like to write my own. So, how would I
have to write a doxia plugin?

Kind regards

Peter

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How to create a site/doxia plugin?

Mark Raynsford-3
On 2018-07-02T13:55:20 +0200
Peter Nabbefeld <[hidden email]> wrote:

> Hello,
>
> I haven't ever written a maven plugin. But, as I'm not satisfied with
> the doxia plugins available, I'd like to write my own. So, how would I
> have to write a doxia plugin?

Here's a plugin I wrote last year and still use to the present day:

  https://github.com/io7m/minisite/

It produces sites that look like this:

  https://www.io7m.com/software/junreachable/

The com.io7m.minisite.core module is independent of Maven, and the
com.io7m.minisite.maven_plugin module implements the actual plugin (by
taking data from the current Maven project and passing it to the core).

One thing you will need to do is unbind the existing Maven site plugin
from the lifecycle in any project that actually uses your plugin
(assuming that you bind your own site plugin to the "site" phase of the
build). Here's an example of how to do this:

  https://github.com/io7m/primogenitor/blob/develop/pom.xml#L908

--
Mark Raynsford | http://www.io7m.com


attachment0 (235 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: How to create a site/doxia plugin?

Peter Nabbefeld

Thank You, this is really an interesting plugin. But I don't want to
break site generation, as I'm using it for other reports like JavaDoc, too.

I just want to write a doxia plugin, if possible, as all text-based
documentation generators seem to be more or less broken or at least not
able to generate the docs in the way I want.

Kind regards

Peter



Am 02.07.2018 um 14:48 schrieb Mark Raynsford:

> On 2018-07-02T13:55:20 +0200
> Peter Nabbefeld <[hidden email]> wrote:
>
>> Hello,
>>
>> I haven't ever written a maven plugin. But, as I'm not satisfied with
>> the doxia plugins available, I'd like to write my own. So, how would I
>> have to write a doxia plugin?
> Here's a plugin I wrote last year and still use to the present day:
>
>    https://github.com/io7m/minisite/
>
> It produces sites that look like this:
>
>    https://www.io7m.com/software/junreachable/
>
> The com.io7m.minisite.core module is independent of Maven, and the
> com.io7m.minisite.maven_plugin module implements the actual plugin (by
> taking data from the current Maven project and passing it to the core).
>
> One thing you will need to do is unbind the existing Maven site plugin
> from the lifecycle in any project that actually uses your plugin
> (assuming that you bind your own site plugin to the "site" phase of the
> build). Here's an example of how to do this:
>
>    https://github.com/io7m/primogenitor/blob/develop/pom.xml#L908
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How to create a site/doxia plugin?

Hervé BOUTEMY
Hi Peter,

What do you call a Doxia plugin?

I see misc interpretations:

- a Doxia module [1], to support a new output format = a new Sink, see the
currfent modules that provide Sinks (and not only parsers) [2]

- a Skin [3], to have a web site that matches better your intent

- a new Maven plugin that integrates reports in another way than maven-site-
plugin and maven-pdf-plugin

Perhaps it's something else: you'll need to describe more precisely what parts
you want to reuse and which part you want to extend

Regards,

Hervé

[1] https://maven.apache.org/doxia/overview.html

[2] https://maven.apache.org/doxia/references/index.html

[3] https://maven.apache.org/skins/index.html

Le mardi 3 juillet 2018, 07:30:19 CEST Peter Nabbefeld a écrit :

> Thank You, this is really an interesting plugin. But I don't want to
> break site generation, as I'm using it for other reports like JavaDoc, too.
>
> I just want to write a doxia plugin, if possible, as all text-based
> documentation generators seem to be more or less broken or at least not
> able to generate the docs in the way I want.
>
> Kind regards
>
> Peter
>
> Am 02.07.2018 um 14:48 schrieb Mark Raynsford:
> > On 2018-07-02T13:55:20 +0200
> >
> > Peter Nabbefeld <[hidden email]> wrote:
> >> Hello,
> >>
> >> I haven't ever written a maven plugin. But, as I'm not satisfied with
> >> the doxia plugins available, I'd like to write my own. So, how would I
> >> have to write a doxia plugin?
> >
> > Here's a plugin I wrote last year and still use to the present day:
> >    https://github.com/io7m/minisite/
> >
> > It produces sites that look like this:
> >    https://www.io7m.com/software/junreachable/
> >
> > The com.io7m.minisite.core module is independent of Maven, and the
> > com.io7m.minisite.maven_plugin module implements the actual plugin (by
> > taking data from the current Maven project and passing it to the core).
> >
> > One thing you will need to do is unbind the existing Maven site plugin
> > from the lifecycle in any project that actually uses your plugin
> > (assuming that you bind your own site plugin to the "site" phase of the
> >
> > build). Here's an example of how to do this:
> >    https://github.com/io7m/primogenitor/blob/develop/pom.xml#L908
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]





---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How to create a site/doxia plugin?

Peter Nabbefeld

Hi Hervé,

sorry for being unspecific - I want some basic support for JspWiki format.

So far, I found https://maven.apache.org/doxia/developers/modules.html,
but it's incomplete and outdated ("SinkFactory" was changed into an
interface, "AbstractSiteModule" seems to no more exist).

Kind regards

Peter



Am 03.07.2018 um 08:14 schrieb Hervé BOUTEMY:

> Hi Peter,
>
> What do you call a Doxia plugin?
>
> I see misc interpretations:
>
> - a Doxia module [1], to support a new output format = a new Sink, see the
> currfent modules that provide Sinks (and not only parsers) [2]
>
> - a Skin [3], to have a web site that matches better your intent
>
> - a new Maven plugin that integrates reports in another way than maven-site-
> plugin and maven-pdf-plugin
>
> Perhaps it's something else: you'll need to describe more precisely what parts
> you want to reuse and which part you want to extend
>
> Regards,
>
> Hervé
>
> [1] https://maven.apache.org/doxia/overview.html
>
> [2] https://maven.apache.org/doxia/references/index.html
>
> [3] https://maven.apache.org/skins/index.html
>
> Le mardi 3 juillet 2018, 07:30:19 CEST Peter Nabbefeld a écrit :
>> Thank You, this is really an interesting plugin. But I don't want to
>> break site generation, as I'm using it for other reports like JavaDoc, too.
>>
>> I just want to write a doxia plugin, if possible, as all text-based
>> documentation generators seem to be more or less broken or at least not
>> able to generate the docs in the way I want.
>>
>> Kind regards
>>
>> Peter
>>
>> Am 02.07.2018 um 14:48 schrieb Mark Raynsford:
>>> On 2018-07-02T13:55:20 +0200
>>>
>>> Peter Nabbefeld <[hidden email]> wrote:
>>>> Hello,
>>>>
>>>> I haven't ever written a maven plugin. But, as I'm not satisfied with
>>>> the doxia plugins available, I'd like to write my own. So, how would I
>>>> have to write a doxia plugin?
>>> Here's a plugin I wrote last year and still use to the present day:
>>>     https://github.com/io7m/minisite/
>>>
>>> It produces sites that look like this:
>>>     https://www.io7m.com/software/junreachable/
>>>
>>> The com.io7m.minisite.core module is independent of Maven, and the
>>> com.io7m.minisite.maven_plugin module implements the actual plugin (by
>>> taking data from the current Maven project and passing it to the core).
>>>
>>> One thing you will need to do is unbind the existing Maven site plugin
>>> from the lifecycle in any project that actually uses your plugin
>>> (assuming that you bind your own site plugin to the "site" phase of the
>>>
>>> build). Here's an example of how to do this:
>>>     https://github.com/io7m/primogenitor/blob/develop/pom.xml#L908
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How to create a site/doxia plugin?

Hervé BOUTEMY
Hi Peter,

IIUC, you want to create a JspWiki parser, to be able to write JspWiki markup
by hand and let maven-site-plugin parse it to integrate into the html site.

That's it?

Then the sink part is not interesting to you: this would to output JspWiki
format instead of html.

I fear I did not check this doc when I changed some bits over versions: there
are probably a few glitches in this doc.
I'll have a look.
In the mean time, just have a look at modules in Doxia itself should help you.

And remember: Parser is what you want to parse JspWiki. Sink is what you don't
need, to output JspWiki: would be useful only if you want to support JspWiki
as output in Doxia converter, for example [1]

Regards,

Hervé

[1] https://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html

Le mardi 3 juillet 2018, 10:20:06 CEST Peter Nabbefeld a écrit :

> Hi Hervé,
>
> sorry for being unspecific - I want some basic support for JspWiki format.
>
> So far, I found https://maven.apache.org/doxia/developers/modules.html,
> but it's incomplete and outdated ("SinkFactory" was changed into an
> interface, "AbstractSiteModule" seems to no more exist).
>
> Kind regards
>
> Peter
>
> Am 03.07.2018 um 08:14 schrieb Hervé BOUTEMY:
> > Hi Peter,
> >
> > What do you call a Doxia plugin?
> >
> > I see misc interpretations:
> >
> > - a Doxia module [1], to support a new output format = a new Sink, see the
> > currfent modules that provide Sinks (and not only parsers) [2]
> >
> > - a Skin [3], to have a web site that matches better your intent
> >
> > - a new Maven plugin that integrates reports in another way than
> > maven-site- plugin and maven-pdf-plugin
> >
> > Perhaps it's something else: you'll need to describe more precisely what
> > parts you want to reuse and which part you want to extend
> >
> > Regards,
> >
> > Hervé
> >
> > [1] https://maven.apache.org/doxia/overview.html
> >
> > [2] https://maven.apache.org/doxia/references/index.html
> >
> > [3] https://maven.apache.org/skins/index.html
> >
> > Le mardi 3 juillet 2018, 07:30:19 CEST Peter Nabbefeld a écrit :
> >> Thank You, this is really an interesting plugin. But I don't want to
> >> break site generation, as I'm using it for other reports like JavaDoc,
> >> too.
> >>
> >> I just want to write a doxia plugin, if possible, as all text-based
> >> documentation generators seem to be more or less broken or at least not
> >> able to generate the docs in the way I want.
> >>
> >> Kind regards
> >>
> >> Peter
> >>
> >> Am 02.07.2018 um 14:48 schrieb Mark Raynsford:
> >>> On 2018-07-02T13:55:20 +0200
> >>>
> >>> Peter Nabbefeld <[hidden email]> wrote:
> >>>> Hello,
> >>>>
> >>>> I haven't ever written a maven plugin. But, as I'm not satisfied with
> >>>> the doxia plugins available, I'd like to write my own. So, how would I
> >>>> have to write a doxia plugin?
> >>>
> >>> Here's a plugin I wrote last year and still use to the present day:
> >>>     https://github.com/io7m/minisite/
> >>>
> >>> It produces sites that look like this:
> >>>     https://www.io7m.com/software/junreachable/
> >>>
> >>> The com.io7m.minisite.core module is independent of Maven, and the
> >>> com.io7m.minisite.maven_plugin module implements the actual plugin (by
> >>> taking data from the current Maven project and passing it to the core).
> >>>
> >>> One thing you will need to do is unbind the existing Maven site plugin
> >>> from the lifecycle in any project that actually uses your plugin
> >>> (assuming that you bind your own site plugin to the "site" phase of the
> >>>
> >>> build). Here's an example of how to do this:
> >>>     https://github.com/io7m/primogenitor/blob/develop/pom.xml#L908
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: [hidden email]
> >> For additional commands, e-mail: [hidden email]
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: [hidden email]
> > For additional commands, e-mail: [hidden email]
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]





---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How to create a site/doxia plugin?

Hervé BOUTEMY
I just updated the documentation: it should be more accurate now
https://maven.apache.org/doxia/developers/modules.html

Regards,

Hervé

Le mercredi 4 juillet 2018, 07:55:25 CEST Hervé BOUTEMY a écrit :

> Hi Peter,
>
> IIUC, you want to create a JspWiki parser, to be able to write JspWiki
> markup by hand and let maven-site-plugin parse it to integrate into the
> html site.
>
> That's it?
>
> Then the sink part is not interesting to you: this would to output JspWiki
> format instead of html.
>
> I fear I did not check this doc when I changed some bits over versions:
> there are probably a few glitches in this doc.
> I'll have a look.
> In the mean time, just have a look at modules in Doxia itself should help
> you.
>
> And remember: Parser is what you want to parse JspWiki. Sink is what you
> don't need, to output JspWiki: would be useful only if you want to support
> JspWiki as output in Doxia converter, for example [1]
>
> Regards,
>
> Hervé
>
> [1] https://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html
>
> Le mardi 3 juillet 2018, 10:20:06 CEST Peter Nabbefeld a écrit :
> > Hi Hervé,
> >
> > sorry for being unspecific - I want some basic support for JspWiki format.
> >
> > So far, I found https://maven.apache.org/doxia/developers/modules.html,
> > but it's incomplete and outdated ("SinkFactory" was changed into an
> > interface, "AbstractSiteModule" seems to no more exist).
> >
> > Kind regards
> >
> > Peter
> >
> > Am 03.07.2018 um 08:14 schrieb Hervé BOUTEMY:
> > > Hi Peter,
> > >
> > > What do you call a Doxia plugin?
> > >
> > > I see misc interpretations:
> > >
> > > - a Doxia module [1], to support a new output format = a new Sink, see
> > > the
> > > currfent modules that provide Sinks (and not only parsers) [2]
> > >
> > > - a Skin [3], to have a web site that matches better your intent
> > >
> > > - a new Maven plugin that integrates reports in another way than
> > > maven-site- plugin and maven-pdf-plugin
> > >
> > > Perhaps it's something else: you'll need to describe more precisely what
> > > parts you want to reuse and which part you want to extend
> > >
> > > Regards,
> > >
> > > Hervé
> > >
> > > [1] https://maven.apache.org/doxia/overview.html
> > >
> > > [2] https://maven.apache.org/doxia/references/index.html
> > >
> > > [3] https://maven.apache.org/skins/index.html
> > >
> > > Le mardi 3 juillet 2018, 07:30:19 CEST Peter Nabbefeld a écrit :
> > >> Thank You, this is really an interesting plugin. But I don't want to
> > >> break site generation, as I'm using it for other reports like JavaDoc,
> > >> too.
> > >>
> > >> I just want to write a doxia plugin, if possible, as all text-based
> > >> documentation generators seem to be more or less broken or at least not
> > >> able to generate the docs in the way I want.
> > >>
> > >> Kind regards
> > >>
> > >> Peter
> > >>
> > >> Am 02.07.2018 um 14:48 schrieb Mark Raynsford:
> > >>> On 2018-07-02T13:55:20 +0200
> > >>>
> > >>> Peter Nabbefeld <[hidden email]> wrote:
> > >>>> Hello,
> > >>>>
> > >>>> I haven't ever written a maven plugin. But, as I'm not satisfied with
> > >>>> the doxia plugins available, I'd like to write my own. So, how would
> > >>>> I
> > >>>> have to write a doxia plugin?
> > >>>
> > >>> Here's a plugin I wrote last year and still use to the present day:
> > >>>     https://github.com/io7m/minisite/
> > >>>
> > >>> It produces sites that look like this:
> > >>>     https://www.io7m.com/software/junreachable/
> > >>>
> > >>> The com.io7m.minisite.core module is independent of Maven, and the
> > >>> com.io7m.minisite.maven_plugin module implements the actual plugin (by
> > >>> taking data from the current Maven project and passing it to the
> > >>> core).
> > >>>
> > >>> One thing you will need to do is unbind the existing Maven site plugin
> > >>> from the lifecycle in any project that actually uses your plugin
> > >>> (assuming that you bind your own site plugin to the "site" phase of
> > >>> the
> > >>>
> > >>> build). Here's an example of how to do this:
> > >>>     https://github.com/io7m/primogenitor/blob/develop/pom.xml#L908
> > >>
> > >> ---------------------------------------------------------------------
> > >> To unsubscribe, e-mail: [hidden email]
> > >> For additional commands, e-mail: [hidden email]
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: [hidden email]
> > > For additional commands, e-mail: [hidden email]
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: [hidden email]
> > For additional commands, e-mail: [hidden email]
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]





---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]