[
https://issues.apache.org/jira/browse/OFBIZ-9423?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jacques Le Roux closed OFBIZ-9423.
----------------------------------
> 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
(v7.6.3#76005)
