You are viewing a plain text version of this content. The canonical link for it is here.

Posted to doxia-users@maven.apache.org by Ahana <ah...@gmail.com> on 2008/12/29 06:16:14 UTC

Recommendation for best format for Maven Documentation

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.

Re: Recommendation for best format for Maven Documentation

Posted by Ahana <ah...@gmail.com>.

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 <ah...@gmail.com>
> 
>>
>> 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@gmail.com
> 
> 

-- 
View this message in context: http://www.nabble.com/Recommendation-for-best-format-for-Maven-Documentation-tp21199191p21207130.html
Sent from the Doxia - Users mailing list archive at Nabble.com.

Re: Recommendation for best format for Maven Documentation

Posted by Lammert Westerhoff <we...@gmail.com>.

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 <ah...@gmail.com>

>
> 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@gmail.com

Re: Recommendation for best format for Maven Documentation

Posted by Ahana <ah...@gmail.com>.

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 <ah...@gmail.com>:
>>
>>  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.
>>
>>
> 
> 

-- 
View this message in context: http://www.nabble.com/Recommendation-for-best-format-for-Maven-Documentation-tp21199191p21207189.html
Sent from the Doxia - Users mailing list archive at Nabble.com.

Re: Recommendation for best format for Maven Documentation

Posted by Vincent Siveton <vi...@gmail.com>.

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 <ah...@gmail.com>:
>
>  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.
>
>