Resolution: Information Provided
Affects Version/s: None
Fix Version/s: None
Here is something I forgot to write months ago, we can now refer to this thread Discussion: documentation framework for OFBiz
In a (now not so much) recent email to dev ML following a Jacopo's suggestion made some time ago, I advocated to put as much as possible documentation in the source to ease the process of separately documenting releases and trunk. I was surprised to not get any attention. So I'll try here to better explain my plan.
Camel way: https://s.apache.org/laG8
While working on
OFBIZ-4941 2,5 years ago, Paul Foxworthy made me discover http://pandoc.org/ which allows to transform a lot of format into another, and in our case especially in HTML (we now know that we will use in 1st place AsciiDoctor and Pandoc when needed)
The idea is to use versionned documentation to generate HTML that can be included in the wiki. So we have less to worry about updating the wiki, only one point of failure. And when we update the source we also update the documentation located just beside. Like for instance it's done at
In those case the versionned documentation is using Mardown in source. But for that using any documenting tool is OK as long as we can transform its format to HTML. Of course it's better to limit the number of documenting tool. But anyway, I guess after some time, only the documenting tool the more adapted to the need will surface (we now commonly decided to use AsciiDoc). So it's not the focus of the discussion.
And it's not only stricly about technical documentation. For instance Using the Birt Report Designer which is part of the Flexible Reports documentation is more intended to final users.
I recently removed the documentation directory from the tools branches because the documentation (any form) must be part of the version (trunk, branches)
At revision: 1757043 I have Added a convenient pandoc.bat as a reminder for now, to be enhanced later (actually I have removed it later and use now this .bat I have locally
Maybe it will become a Gradle task rather or maybe even several Gradle tasks if we use a CONTRIBUTING-template.md and other possible *.md files (not sure which CONTRIBUTING-template.md I was then speaking about - I guess one of those you can find on GitHub- not even sure of the idea here, I'll check later again)