Uploaded image for project: 'OFBiz'
  1. OFBiz
  2. OFBIZ-9423

Update wiki documentation from source

    XMLWordPrintableJSON

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Minor
    • Resolution: Information Provided
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Confluence
    • Labels:
      None

      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)

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                jleroux Jacques Le Roux
                Reporter:
                jleroux Jacques Le Roux
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: