Recommendation for best format for Maven Documentation

[Ahana]

Hello Folks,

I need to move documentation from various formats like Wiki and HTML and move it to Maven and generate a site as well as a book. Key requirements are ease of use, cross-referencing, images, headers & footers. Could someone with experience building something similar recommend the best format and editing tools to do this?

Thanks,
A

[Lammert Westerhoff]

Hi,
There are various ways of doing this. I also did similar work like moving
docs from Wiki to Maven. To generate the Maven websites I mainly used the
APT format. I have no experience in working with XDoc but I think its
worthed to look into this as an alternative as well. Besides that, I also
created a small maven plugin that allows me to generate docs from Java code,
to for example generate a table from a Java enum. This is quite simple to
make when using the Doxia Sink API.

I think the best way forward is to read the docs on
http://maven.apache.org/doxia/ if you haven't already.

Hope this helps.

Regards

2008/12/29 Ahana <ahana.tur@...>

>
> Hello Folks,
>
> I need to move documentation from various formats like Wiki and HTML and
> move it to Maven and generate a site as well as a book. Key requirements
> are
> ease of use, cross-referencing, images, headers & footers. Could someone
> with experience building something similar recommend the best format and
> editing tools to do this?
>
> Thanks,
> A
> --
> View this message in context:
> http://www.nabble.com/Recommendation-for-best-format-for-Maven-Documentation-tp21199191p21199191.html
> Sent from the Doxia - Users mailing list archive at Nabble.com.
>
>

--
Lammert Westerhoff
westerhoff@...

[Vincent Siveton]

Hi Ahana,

- which Wiki? Doxia supports TWiki and confluence out-of-box.
- who are writing doc? APT/xdoc are meanly for dev (btw we have an
editor in m2e eclipse plugin).
- You could easily convert wiki+html to apt or xdoc via doxia-converter [1]
- if header/footer are on your all pages, you need to remove them first.

Cheers,

Vincent

[1] http://svn.apache.org/repos/asf/maven/doxia/doxia-tools/trunk/doxia-converter

2008/12/29, Ahana <ahana.tur@...>:

>
>  Hello Folks,
>
>  I need to move documentation from various formats like Wiki and HTML and
>  move it to Maven and generate a site as well as a book. Key requirements are
>  ease of use, cross-referencing, images, headers & footers. Could someone
>  with experience building something similar recommend the best format and
>  editing tools to do this?
>
>  Thanks,
>  A
>
> --
>  View this message in context: http://www.nabble.com/Recommendation-for-best-format-for-Maven-Documentation-tp21199191p21199191.html
>  Sent from the Doxia - Users mailing list archive at Nabble.com.
>
>

[Ahana]

Thanks for the prompt response. Were you able to cross-reference and use headers and footers
using APT? Ideally, I would like to use APT because its simple but I haven't been able to locate
APT documentation related to the above mentioned features.

Lammert Westerhoff wrote:

Hi,
There are various ways of doing this. I also did similar work like moving
docs from Wiki to Maven. To generate the Maven websites I mainly used the
APT format. I have no experience in working with XDoc but I think its
worthed to look into this as an alternative as well. Besides that, I also
created a small maven plugin that allows me to generate docs from Java code,
to for example generate a table from a Java enum. This is quite simple to
make when using the Doxia Sink API.

I think the best way forward is to read the docs on
http://maven.apache.org/doxia/ if you haven't already.

Hope this helps.

Regards

2008/12/29 Ahana <[e-mail]>

>
> Hello Folks,
>
> I need to move documentation from various formats like Wiki and HTML and
> move it to Maven and generate a site as well as a book. Key requirements
> are
> ease of use, cross-referencing, images, headers & footers. Could someone
> with experience building something similar recommend the best format and
> editing tools to do this?
>
> Thanks,
> A
> --
> View this message in context:
> http://www.nabble.com/Recommendation-for-best-format-for-Maven-Documentation-tp21199191p21199191.html
> Sent from the Doxia - Users mailing list archive at Nabble.com.
>
>


--
Lammert Westerhoff
[e-mail]

[Ahana]

Thanks, Vincent.  My responses:
-I have to convert MediaWiki docs.
-The developers are expected to update the documents once I set up the structure.

Do APT and XDoc both support cross-references, headers and footers?

Vincent Siveton wrote:

Hi Ahana,

- which Wiki? Doxia supports TWiki and confluence out-of-box.
- who are writing doc? APT/xdoc are meanly for dev (btw we have an
editor in m2e eclipse plugin).
- You could easily convert wiki+html to apt or xdoc via doxia-converter [1]
- if header/footer are on your all pages, you need to remove them first.

Cheers,

Vincent

[1] http://svn.apache.org/repos/asf/maven/doxia/doxia-tools/trunk/doxia-converter

2008/12/29, Ahana <[e-mail]>:
>
>  Hello Folks,
>
>  I need to move documentation from various formats like Wiki and HTML and
>  move it to Maven and generate a site as well as a book. Key requirements are
>  ease of use, cross-referencing, images, headers & footers. Could someone
>  with experience building something similar recommend the best format and
>  editing tools to do this?
>
>  Thanks,
>  A
>
> --
>  View this message in context: http://www.nabble.com/Recommendation-for-best-format-for-Maven-Documentation-tp21199191p21199191.html
>  Sent from the Doxia - Users mailing list archive at Nabble.com.
>
>