[
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)
