Excellent news Taher! Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
Thanks Sharan On 2018-01-12 17:36, Taher Alkhateeb <slidingfilame...@gmail.com> wrote: > Hello everyone, > > Sorry for the delay on my part, I got a little preoccupied. Anyway, I > have a small patch in [1] that provides the PoC for integrating > asciidoctor with OFBiz. I also provided in the the JIRA [1] > instructions on how to run it. Essentially, this allows you to create > documentation for any component by simply creating a src/docs/asciidoc > directory and putting files inside. > > This solution is flexible and allows us to build bigger designs on top > of it. Please review it and tell me if you like the general design. > > [1] https://issues.apache.org/jira/browse/OFBIZ-9873 > > On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb > <slidingfilame...@gmail.com> wrote: > > Hello Folks, > > > > We've had this discussion multiple times in the past, but I think I > > have a more concrete idea this time for solving this problem. In the > > past few weeks we've been working internally in Pythys to figure out > > the best way to write and distribute documentation, and I think most > > of that is applicable to OFBiz. > > > > In a nutshell, here is the idea (practically) for how to proceed: > > > > - The documentation language to use is Asciidoc > > - The documentation tool is Asciidoctor > > - Publishing happens through Gradle using the asciidoctor gradle > > plugin (not the OFBiz framework or anything else). > > - The only place where we write documentation is inside the code base > > - Every component contains its own documentation > > - General documentation goes to either a standalone directory or a > > generic component like common or base > > - As much as possible, documentation files are small and focused on > > one topic. And then other longer documents are constructed from these > > snippets of documentation. > > - We publish to all formats including PDF for users, or HTML for > > embedded help and wiki pages. So OFBiz does not parse docbook for its > > help system, instead it just renders generated HTML. > > > > As I've worked extensively with Asciidoc I find it easy to pickup > > (like markdown) but also modular (like docbook and dita). It's also > > neat that you can sprinkle variables all around in your document so > > that update is no longer a painful grepping process. > > > > Would love to hear your thoughts on this. > > > > Cheers, > > > > Taher Alkhateeb >
