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
