Project documentation environment

[Stefano Maestri]

Hi guys,

I've started working on 

https://github.com/ironjacamar/ironjacamar/issues/528

I've evaluated DocBook and AsciiDoc, and my choice would be for the second because it have some pluses:

• Generate different format: HTML and PDF of course, but also ePub in a nutshell. I think having documentation in eReader format is great nowdays
• GitHub render AsciiDoc natively in project repository web site (using asciidoctor)
• it has a cool source code highlighter http://www.methods.co.nz/asciidoc/source-highlight-filter.html
• Markdown are easy to learn
• Support for almost IDE and text editor (Vim, Emacs, Eclipse, IntelliJ)
• a2x toolchain wrapper makes easy any format generation directly from asciidoc even from command line
• Gradle support of AsciidoctorTask make easy integration w/ our build

Of course any comment or different point of view are more than welcome

I'll create a PR w/ anew module and build extension for asciidoc soon. Of course first commit will have minimal documentation content and it will be extended later.

I'll keep ML post of my progresses.

regards

S.

[Jesper Pedersen]

AsciiDoc sounds like a good choice - looking forward to seeing how it integrates.

[Stefano Maestri]

PR sent:

https://github.com/ironjacamar/ironjacamar/pull/529

It supports html5, pdf, epub and docbook output.

Please note epub output needs documentation books organized with a main document (called spine document) just including other documents w/o any content. I organized the enviroment to have an asciidoc for each chapter.

Current contents anre just a mock developer-guide. Next task will be to provide correct contents.

any feedback are more than welcome

S.

[Jesper Pedersen]

Looks good.

A few comments:

• We should keep dependency versions in the top-level build.gradle file
• The PDFs should go in the 'doc' directory in the distribution
• The HTMLs should be deployed into the root.war for web-server in the distribution

You can see how much of the documentation branding from 1.x you can port - logos and color scheme.

I think for initial content it could be enough with a high level view of the project, and how to contribute.

[Stefano Maestri]

Hi all,

I've just merged changes to the project including documentation environment based on asciidoc w/ fixes suggested by Jesper.

This merge includes also a porting in asciidoc syntax of our developr-guide. I already updated chapters about github, building, uissue tracker and so on.

Please have a look and post here any feedback. I'll not be around next week, but I'll take care as soon as I'll come back.

regards

S.