Hi Gil, There is nothing simpler than linking docs together. Code snippet:
include::relative/path/to/document/document-name.adoc[] Wow right :) On Mon, Jan 15, 2018 at 11:15 AM, gil portenseigne <gil.portensei...@nereide.fr> wrote: > Hello Taher, > > I did try your patch and played a bit with the asciidoctor integration you > provide, this week-end. > > That's quite simple, i like it, i will play a bit more with it to find the > good way to links docs files between them. > > Thanks ! > > Gil > > > > On 12/01/2018 17:36, Taher Alkhateeb 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 > >
