You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ofbiz.apache.org by "Jacques Le Roux (JIRA)" <ji...@apache.org> on 2017/11/13 07:31:00 UTC
[jira] [Updated] (OFBIZ-9423) Update wiki documentation from source
[ https://issues.apache.org/jira/browse/OFBIZ-9423?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Jacques Le Roux updated OFBIZ-9423:
-----------------------------------
Description:
Here is something I forgot to write months ago, we can now refer to this thread [Discussion: documentation framework for OFBiz|http://markmail.org/message/fzdwlr2ieud3xzoq]
[In a (now not so much) recent email to dev ML|https://s.apache.org/KyuT] 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|https://s.apache.org/srMs] 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|https://svn.apache.org/repos/asf/ofbiz/ofbiz-plugins/trunk/birt/documents/Using%20the%20Birt%20Report%20Designer.md.html] 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
{code}
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\"
{code}
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)
was:WIP...
> Update wiki documentation from source
> -------------------------------------
>
> Key: OFBIZ-9423
> URL: https://issues.apache.org/jira/browse/OFBIZ-9423
> Project: OFBiz
> Issue Type: Improvement
> Components: Confluence
> Reporter: Jacques Le Roux
> Assignee: Jacques Le Roux
> Priority: Minor
>
> Here is something I forgot to write months ago, we can now refer to this thread [Discussion: documentation framework for OFBiz|http://markmail.org/message/fzdwlr2ieud3xzoq]
> [In a (now not so much) recent email to dev ML|https://s.apache.org/KyuT] 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|https://s.apache.org/srMs] 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|https://svn.apache.org/repos/asf/ofbiz/ofbiz-plugins/trunk/birt/documents/Using%20the%20Birt%20Report%20Designer.md.html] 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
> {code}
> 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\"
> {code}
> 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)
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)