Also thinking about it just after clicking send, maybe there is no need for the publishComponentDocs and publishAllComponentsDocs tasks because we should treat all OFBiz documentation as one piece. and Instead we can have a ./gradlew publishPluginDocs. So throwing another idea in the pile
On Wed, Jan 17, 2018 at 6:54 PM, Taher Alkhateeb <slidingfilame...@gmail.com> wrote: > So I have thought of a few ways to implement our documentation > structure and I would like to share my ideas with everyone to see what > you prefer to go with. Here goes: > > - First, let's categorize documentation as: > - component-specific > - general documentation > - component specific documentation lives inside the component in > "/src/docs/asciidoc". It is a self contained piece of documentation. > - Every component has only _one_ publishable document. There is a > methodology in asciidoctor to denote public and private documents. > private documents will not be published but only included in other > documents. This way we can make a modular documentation for each > component while publishing only one output. > - general documentation (i'm still scratching my head over this one) > could be placed maybe in framework/base. What it does is explain high > level information about the framework and explain general conceptual > principles of how things work. > - We can combine the entire documentation of everything (framework + > applications) in a single document that references all the other > documents and maybe we can place it at the top-level directory and > call it something like ofbiz-documentation.adoc > - Plugins are not included in the full documentation, they are self > contained and are not part of the _big_ published manual. instead each > plugin has its own mini manual. > - We declare three gradle tasks similar to the below: > - "./gradlew publishComponentDocs": publish documentation for a > specific component / plugin which requires a componentName flag. > - "./gradlew publishAllComponentsDocs": publish documentation for > all components / plugins > - "./gradlew publishOfbizDocs": publish the master documentation > manual that combines everything. > > This is a brain dump so I leave it to you fine folks to refine the > ideas and decide where we should go. > > Cheers, > > Taher Alkhateeb > > On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <cr...@fossfolks.com> wrote: >> I think the doc structure ought to mirror the menu in the software, or are >> you talking about how a doc itself is laid out? >> >> >> >> On 01/17/2018 09:25 AM, Sharan Foga wrote: >>> >>> Hi Taher >>> >>> Great work! I tried it out and found it simple and easy to use (and >>> write!). When can we start writing ? :-) >>> >>> I was thinking to start with basic descriptions of each of the >>> applications, then see how it evolves from there. We can maybe recover some >>> documentation content from various sources including our existing online >>> help system and the wiki. >>> >>> The documentation structure will maybe need some thought, and we may need >>> to sort out some common template or guidelines around it. >>> >>> Thanks >>> Sharan >>> >>> On 2018-01-14 12:33, "Sharan Foga"<sha...@apache.org> wrote: >>>> >>>> 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 >> >>
