[OFBIZ-9423] Update wiki documentation from source

• Type: Improvement
• Status: Closed
• Priority: Minor
• Resolution: Information Provided
• Component/s: Confluence
• Assignee: Jacques Le Roux
• Reporter: Jacques Le Roux
• Created: 20/Jun/17 08:53
• Updated: 16/Nov/18 09:07
• Resolved: 16/Nov/18 09:07

Description

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
https://cwiki.apache.org/confluence/display/OFBIZ/From+Ant+to+Gradle+-+R16.11+version
https://cwiki.apache.org/confluence/display/OFBIZ/From+Ant+to+Gradle+-+trunk+version
or
https://cwiki.apache.org/confluence/display/OFBIZ/Birt+Flexible+Reports?src=search

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

pandoc README.md -s -o tools/wiki-files/README.md.html

pandoc themes/README.md -s -o tools/wiki-files/themes/README.md.html

pandoc "plugins/birt/documents/Creating reports.md" -s -o "tools/wiki-files/birt/Creating reports.md.html"
pandoc "plugins/birt/documents/Using the Birt Report Designer.md" -s -o "tools/wiki-files/birt/Using the Birt Report Designer.md.html"
pandoc "plugins/birt/documents/How to use flexible reports.md" -s -o "tools/wiki-files/birt/How to use flexible reports.md.html"
pandoc "plugins/birt/documents/Report master creation.md" -s -o "tools/wiki-files/birt/Report master creation.md.html"

pandoc tools/demo-backup/README.MD -s -o tools/wiki-files/demos/README.md.html

cd tools
TortoiseProc /command:commit /path:"C:\projectsASF\ofbiz\tools*C:\projectsASF\ofbiz\"

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)

Issue Links

• is a child of: OFBIZ-10285 OFBiz Documentation Global Task