Re: [Discussion] documentation framework for OFBiz
On 2018/03/13 16:37:31, Taher Alkhateeb wrote: > Hey guys, feature implemented in r1826656. Now both plugins and ofbiz > manual will delete before re-generating their artifacts. I believe > this will solve the problem and I think we won't have a big problem > with performance, and probably won't be until we reach maybe thousands > of documents. > > By the way, may I also recommend that we minimize the number of > documents in the beginning. So instead of creating new files, just > create new headers, and split the file later when it gets too big. > This way we do not overly complicate the design unless it makes sense. Good point and agreed. Let's get some content in and see how it evolves. Thanks Sharan > > On Mon, Mar 12, 2018 at 6:44 PM, Sharan Foga wrote: > > Hi Taher > > > > Manually deleting and regenerating is what I've been doing :-) so it could > > be a start. We are evolving - right? We might need to look at it again if > > it becomes an issue as we fill up the content.. > > > > Thanks > > Sharan > > > > > > On 2018/03/12 15:38:44, Taher Alkhateeb wrote: > >> Maybe one way to accomplish this is to delete and regenerate every > >> time. What do you think of that? > >> > >> On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl > >> wrote: > >> > Hi Taher, > >> > > >> > I worked on the documentation over the weekend. > >> > > >> > It would be very nice if the documentation gets updated even if the main > >> > document has not changed. If you change only included documents, the > >> > change > >> > does not go into the main document. > >> > > >> > I briefly searched for a configuration parameter but did not find any. > >> > > >> > Best regards, > >> > > >> > Michael > >> > > >> > > >> > Am 24.02.18 um 15:44 schrieb Michael Brohl: > >> >> > >> >> I have tried Taher's latest patch and it is working great for me. I used > >> >> Intellij Idea with the Asciidoc Plugin. > >> >> > >> >> > >> >> Differently from Olivier's observation, the main developer-manual ist > >> >> updated when I make a change in developer-manual.adoc. Both html and pdf > >> >> include the change. > >> >> > >> >> It is not updated when I only change an included document like > >> >> accounting.adoc. I think it would be good to recreate all files if they > >> >> have > >> >> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has > >> >> not > >> >> be changed even if it is rewritten so it should be no problem. > >> >> > >> >> I think this is a good starting point, more pints might come up if we > >> >> use > >> >> it more intensely. > >> >> > >> >> Thanks, > >> >> > >> >> Michael > >> >> > >> >> > >> >> Am 21.02.18 um 14:08 schrieb Olivier Heintz: > >> >>> > >> >>> Thank you for the work, Taher > >> >>> > >> >>> I have played with it and merge with my tests. > >> >>> Currently, I have start from Accounting_Agreement, convert from docbook > >> >>> and update and > >> >>> test renderer by both your gradle task and by AsciidocFx html button > >> >>> > >> >>> With a lot of include, result html file would be very large and in some > >> >>> case it will be good to be able to put a link in place > >> >>> of include. Currenlty the generateOfbizDocumentation task doesn't > >> >>> generate file for doc in component even if the adoc file is > >> >>> not in the _include directory. > >> >>> > >> >>> Just for information: With AsciidocFx (I have understood it use > >> >>> asciidoctor for generate html file, but I'm not sure) > >> >>> it's not necessary to say include file is in _include directory, it > >> >>> read > >> >>> both in the current directory and in the _include one. > >> >>> The generateOfbizDocumentation task doesn't use the same rule, we > >> >>> should > >> >>> say explicitly it's in the _include directory. > >> >>> > >> >>> The main "malfunction" of the generateOfbizDocumentation task is that > >> >>> it > >> >>> not re-generate the html file if it already exist > >> >>> even if the main adoc file was modified. So it's needed to remove it > >> >>> manually before call generateOfbizDocumentation. > >> >>> > >> >>> Thank you for your usage of leveloffset, it's generated by docbook > >> >>> conversion, but now I understand how it works ;-) > >> >>> > >> >>> > >> >>> Olivier > >> >>> > >> >>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : > >> > >> Hello documentation team and everyone > >> > >> I have created a slightly modified design of the documentation > >> framework with some sample contents in [1]. I highlight the changes > >> below: > >> - Created a new top-level directory called "docs/asciidoc". The reason > >> is so that we have more than one possible manual. > >> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc > >> - Created "Apache OFBiz Developer Manual" in > >> docs/asciidoc/developer-manual.adoc > >> - Created a sample document in the accounting component to show how > >> documents are linked togeth
Re: [Discussion] documentation framework for OFBiz
Hey guys, feature implemented in r1826656. Now both plugins and ofbiz manual will delete before re-generating their artifacts. I believe this will solve the problem and I think we won't have a big problem with performance, and probably won't be until we reach maybe thousands of documents. By the way, may I also recommend that we minimize the number of documents in the beginning. So instead of creating new files, just create new headers, and split the file later when it gets too big. This way we do not overly complicate the design unless it makes sense. On Mon, Mar 12, 2018 at 6:44 PM, Sharan Foga wrote: > Hi Taher > > Manually deleting and regenerating is what I've been doing :-) so it could > be a start. We are evolving - right? We might need to look at it again if it > becomes an issue as we fill up the content.. > > Thanks > Sharan > > > On 2018/03/12 15:38:44, Taher Alkhateeb wrote: >> Maybe one way to accomplish this is to delete and regenerate every >> time. What do you think of that? >> >> On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl >> wrote: >> > Hi Taher, >> > >> > I worked on the documentation over the weekend. >> > >> > It would be very nice if the documentation gets updated even if the main >> > document has not changed. If you change only included documents, the change >> > does not go into the main document. >> > >> > I briefly searched for a configuration parameter but did not find any. >> > >> > Best regards, >> > >> > Michael >> > >> > >> > Am 24.02.18 um 15:44 schrieb Michael Brohl: >> >> >> >> I have tried Taher's latest patch and it is working great for me. I used >> >> Intellij Idea with the Asciidoc Plugin. >> >> >> >> >> >> Differently from Olivier's observation, the main developer-manual ist >> >> updated when I make a change in developer-manual.adoc. Both html and pdf >> >> include the change. >> >> >> >> It is not updated when I only change an included document like >> >> accounting.adoc. I think it would be good to recreate all files if they >> >> have >> >> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has >> >> not >> >> be changed even if it is rewritten so it should be no problem. >> >> >> >> I think this is a good starting point, more pints might come up if we use >> >> it more intensely. >> >> >> >> Thanks, >> >> >> >> Michael >> >> >> >> >> >> Am 21.02.18 um 14:08 schrieb Olivier Heintz: >> >>> >> >>> Thank you for the work, Taher >> >>> >> >>> I have played with it and merge with my tests. >> >>> Currently, I have start from Accounting_Agreement, convert from docbook >> >>> and update and >> >>> test renderer by both your gradle task and by AsciidocFx html button >> >>> >> >>> With a lot of include, result html file would be very large and in some >> >>> case it will be good to be able to put a link in place >> >>> of include. Currenlty the generateOfbizDocumentation task doesn't >> >>> generate file for doc in component even if the adoc file is >> >>> not in the _include directory. >> >>> >> >>> Just for information: With AsciidocFx (I have understood it use >> >>> asciidoctor for generate html file, but I'm not sure) >> >>> it's not necessary to say include file is in _include directory, it read >> >>> both in the current directory and in the _include one. >> >>> The generateOfbizDocumentation task doesn't use the same rule, we should >> >>> say explicitly it's in the _include directory. >> >>> >> >>> The main "malfunction" of the generateOfbizDocumentation task is that it >> >>> not re-generate the html file if it already exist >> >>> even if the main adoc file was modified. So it's needed to remove it >> >>> manually before call generateOfbizDocumentation. >> >>> >> >>> Thank you for your usage of leveloffset, it's generated by docbook >> >>> conversion, but now I understand how it works ;-) >> >>> >> >>> >> >>> Olivier >> >>> >> >>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : >> >> Hello documentation team and everyone >> >> I have created a slightly modified design of the documentation >> framework with some sample contents in [1]. I highlight the changes >> below: >> - Created a new top-level directory called "docs/asciidoc". The reason >> is so that we have more than one possible manual. >> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc >> - Created "Apache OFBiz Developer Manual" in >> docs/asciidoc/developer-manual.adoc >> - Created a sample document in the accounting component to show how >> documents are linked together. >> - Used a special directive called "leveloffset" in the include >> directive. This directive shifts the headers of the included document >> (H2 becomes H3, and so on) so that sub-sections can be published >> separately. >> - Created a task called generateOfbizDocumentation to generate the >> documentation (both PDF and HTML) for framework + core apps >> - Created a task called
Re: [Discussion] documentation framework for OFBiz
If the asciidoctor plugin provides no smarter way, I think this would be ok. The documentation generation process is fast (at least with the few pages we have) so this should be no problem. Thanks, Michael Am 12.03.18 um 16:38 schrieb Taher Alkhateeb: Maybe one way to accomplish this is to delete and regenerate every time. What do you think of that? On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl wrote: Hi Taher, I worked on the documentation over the weekend. It would be very nice if the documentation gets updated even if the main document has not changed. If you change only included documents, the change does not go into the main document. I briefly searched for a configuration parameter but did not find any. Best regards, Michael Am 24.02.18 um 15:44 schrieb Michael Brohl: I have tried Taher's latest patch and it is working great for me. I used Intellij Idea with the Asciidoc Plugin. Differently from Olivier's observation, the main developer-manual ist updated when I make a change in developer-manual.adoc. Both html and pdf include the change. It is not updated when I only change an included document like accounting.adoc. I think it would be good to recreate all files if they have chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not be changed even if it is rewritten so it should be no problem. I think this is a good starting point, more pints might come up if we use it more intensely. Thanks, Michael Am 21.02.18 um 14:08 schrieb Olivier Heintz: Thank you for the work, Taher I have played with it and merge with my tests. Currently, I have start from Accounting_Agreement, convert from docbook and update and test renderer by both your gradle task and by AsciidocFx html button With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is not in the _include directory. Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure) it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one. The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory. The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation. Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-) Olivier Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: Hi Taher I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed. We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!). My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-) Thanks Sharan On 2018/01/28 10:12:41, Taher Alkhateeb wrote: Like Michael I think it is also a minor point. The reason I chose this structure is because it is the default one for asciidoctor and is flexible for the future, so Paul also makes a good point. Any stru
Re: [Discussion] documentation framework for OFBiz
Hi Taher Manually deleting and regenerating is what I've been doing :-) so it could be a start. We are evolving - right? We might need to look at it again if it becomes an issue as we fill up the content.. Thanks Sharan On 2018/03/12 15:38:44, Taher Alkhateeb wrote: > Maybe one way to accomplish this is to delete and regenerate every > time. What do you think of that? > > On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl > wrote: > > Hi Taher, > > > > I worked on the documentation over the weekend. > > > > It would be very nice if the documentation gets updated even if the main > > document has not changed. If you change only included documents, the change > > does not go into the main document. > > > > I briefly searched for a configuration parameter but did not find any. > > > > Best regards, > > > > Michael > > > > > > Am 24.02.18 um 15:44 schrieb Michael Brohl: > >> > >> I have tried Taher's latest patch and it is working great for me. I used > >> Intellij Idea with the Asciidoc Plugin. > >> > >> > >> Differently from Olivier's observation, the main developer-manual ist > >> updated when I make a change in developer-manual.adoc. Both html and pdf > >> include the change. > >> > >> It is not updated when I only change an included document like > >> accounting.adoc. I think it would be good to recreate all files if they > >> have > >> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not > >> be changed even if it is rewritten so it should be no problem. > >> > >> I think this is a good starting point, more pints might come up if we use > >> it more intensely. > >> > >> Thanks, > >> > >> Michael > >> > >> > >> Am 21.02.18 um 14:08 schrieb Olivier Heintz: > >>> > >>> Thank you for the work, Taher > >>> > >>> I have played with it and merge with my tests. > >>> Currently, I have start from Accounting_Agreement, convert from docbook > >>> and update and > >>> test renderer by both your gradle task and by AsciidocFx html button > >>> > >>> With a lot of include, result html file would be very large and in some > >>> case it will be good to be able to put a link in place > >>> of include. Currenlty the generateOfbizDocumentation task doesn't > >>> generate file for doc in component even if the adoc file is > >>> not in the _include directory. > >>> > >>> Just for information: With AsciidocFx (I have understood it use > >>> asciidoctor for generate html file, but I'm not sure) > >>> it's not necessary to say include file is in _include directory, it read > >>> both in the current directory and in the _include one. > >>> The generateOfbizDocumentation task doesn't use the same rule, we should > >>> say explicitly it's in the _include directory. > >>> > >>> The main "malfunction" of the generateOfbizDocumentation task is that it > >>> not re-generate the html file if it already exist > >>> even if the main adoc file was modified. So it's needed to remove it > >>> manually before call generateOfbizDocumentation. > >>> > >>> Thank you for your usage of leveloffset, it's generated by docbook > >>> conversion, but now I understand how it works ;-) > >>> > >>> > >>> Olivier > >>> > >>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : > > Hello documentation team and everyone > > I have created a slightly modified design of the documentation > framework with some sample contents in [1]. I highlight the changes > below: > - Created a new top-level directory called "docs/asciidoc". The reason > is so that we have more than one possible manual. > - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc > - Created "Apache OFBiz Developer Manual" in > docs/asciidoc/developer-manual.adoc > - Created a sample document in the accounting component to show how > documents are linked together. > - Used a special directive called "leveloffset" in the include > directive. This directive shifts the headers of the included document > (H2 becomes H3, and so on) so that sub-sections can be published > separately. > - Created a task called generateOfbizDocumentation to generate the > documentation (both PDF and HTML) for framework + core apps > - Created a task called generatePluginDocumentation > -PpluginId=whatever to generate the documentation for a single plugin. > > That's it. It's simple, easy to understand and I think you might like > it. Any feedback is welcome, and I'll talk to you soon over Skype. > > [1] https://issues.apache.org/jira/browse/OFBIZ-9873 > > On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: > > > > Hi Taher > > > > I think a documentation team would be a great idea. There are people > > that have indicated that they'd like to help out with documentation > > tasks on > > the user list so that is where I'd recruit some people from. As long as > > people know what they need to do to create
Re: [Discussion] documentation framework for OFBiz
Maybe one way to accomplish this is to delete and regenerate every time. What do you think of that? On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl wrote: > Hi Taher, > > I worked on the documentation over the weekend. > > It would be very nice if the documentation gets updated even if the main > document has not changed. If you change only included documents, the change > does not go into the main document. > > I briefly searched for a configuration parameter but did not find any. > > Best regards, > > Michael > > > Am 24.02.18 um 15:44 schrieb Michael Brohl: >> >> I have tried Taher's latest patch and it is working great for me. I used >> Intellij Idea with the Asciidoc Plugin. >> >> >> Differently from Olivier's observation, the main developer-manual ist >> updated when I make a change in developer-manual.adoc. Both html and pdf >> include the change. >> >> It is not updated when I only change an included document like >> accounting.adoc. I think it would be good to recreate all files if they have >> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not >> be changed even if it is rewritten so it should be no problem. >> >> I think this is a good starting point, more pints might come up if we use >> it more intensely. >> >> Thanks, >> >> Michael >> >> >> Am 21.02.18 um 14:08 schrieb Olivier Heintz: >>> >>> Thank you for the work, Taher >>> >>> I have played with it and merge with my tests. >>> Currently, I have start from Accounting_Agreement, convert from docbook >>> and update and >>> test renderer by both your gradle task and by AsciidocFx html button >>> >>> With a lot of include, result html file would be very large and in some >>> case it will be good to be able to put a link in place >>> of include. Currenlty the generateOfbizDocumentation task doesn't >>> generate file for doc in component even if the adoc file is >>> not in the _include directory. >>> >>> Just for information: With AsciidocFx (I have understood it use >>> asciidoctor for generate html file, but I'm not sure) >>> it's not necessary to say include file is in _include directory, it read >>> both in the current directory and in the _include one. >>> The generateOfbizDocumentation task doesn't use the same rule, we should >>> say explicitly it's in the _include directory. >>> >>> The main "malfunction" of the generateOfbizDocumentation task is that it >>> not re-generate the html file if it already exist >>> even if the main adoc file was modified. So it's needed to remove it >>> manually before call generateOfbizDocumentation. >>> >>> Thank you for your usage of leveloffset, it's generated by docbook >>> conversion, but now I understand how it works ;-) >>> >>> >>> Olivier >>> >>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: > > Hi Taher > > I think a documentation team would be a great idea. There are people > that have indicated that they'd like to help out with documentation tasks > on > the user list so that is where I'd recruit some people from. As long as > people know what they need to do to create the patches then it will > become a > funnel process of getting it committed. > > We need a plan to consolidate the information sitting in the wiki and > getting it put into the documentation framework (and this work will then > significantly clear up the wiki!). > > My availability is pretty bad this week so hope to pick this up again > or start the recruitment campaign next week :-) > > Thanks > Sharan > > On 2018/01/28 10:12:41, Taher Alkhateeb >>
Re: [Discussion] documentation framework for OFBiz
Hi Taher, I worked on the documentation over the weekend. It would be very nice if the documentation gets updated even if the main document has not changed. If you change only included documents, the change does not go into the main document. I briefly searched for a configuration parameter but did not find any. Best regards, Michael Am 24.02.18 um 15:44 schrieb Michael Brohl: I have tried Taher's latest patch and it is working great for me. I used Intellij Idea with the Asciidoc Plugin. Differently from Olivier's observation, the main developer-manual ist updated when I make a change in developer-manual.adoc. Both html and pdf include the change. It is not updated when I only change an included document like accounting.adoc. I think it would be good to recreate all files if they have chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not be changed even if it is rewritten so it should be no problem. I think this is a good starting point, more pints might come up if we use it more intensely. Thanks, Michael Am 21.02.18 um 14:08 schrieb Olivier Heintz: Thank you for the work, Taher I have played with it and merge with my tests. Currently, I have start from Accounting_Agreement, convert from docbook and update and test renderer by both your gradle task and by AsciidocFx html button With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is not in the _include directory. Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure) it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one. The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory. The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation. Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-) Olivier Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: Hi Taher I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed. We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!). My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-) Thanks Sharan On 2018/01/28 10:12:41, Taher Alkhateeb wrote: Like Michael I think it is also a minor point. The reason I chose this structure is because it is the default one for asciidoctor and is flexible for the future, so Paul also makes a good point. Any structure is fine by me, the real important work is getting the documentation right which is very exciting to me. I will create a patch soon for a base level structure and publishing options for both HTML and PDF. It would be fantastic if we can unify _all_ of our documentation here including stuff currently in the wiki. This way any changes to code are reflected (probabl
Re: [Discussion] documentation framework for OFBiz
No problem Taher, please take your time. It was just a thought while playing with your PoC, it's not urgent. Am 24.02.18 um 16:30 schrieb Taher Alkhateeb: One of the design goals I had in mind is to make things publishable from the component as well as from the master manual. To do that, I need to think of a proper way for handling all kinds of artifacts like images, and sub-content. So I can't answer you immediately without some review first. I'll provide a patch as soon as I've figured it out. It's a bit tricky because the images directory shifts and is handled differently based on your location in the directory structure. On Sat, Feb 24, 2018 at 6:15 PM, Michael Brohl wrote: Hi Taher, maybe it's enough to only define a convention, like an include directory below each documentation folder? src / docs / asciidoc / includes ord maybe src / docs / includes if they should be reusable also with other documentation frameworks? Am 24.02.18 um 16:12 schrieb Taher Alkhateeb: I haven't yet setup the images variables yet, but it is relatively trivial. For now you can simply include using a relative directory format. I will update the PoC to include images On Sat, Feb 24, 2018 at 6:10 PM, Michael Brohl wrote: I have a question regarding included media files (images etc.) for documentation. Where are they supposed to be stored? Regards, Michael Brohl ecomify GmbH www.ecomify.de Am 24.02.18 um 15:44 schrieb Michael Brohl: I have tried Taher's latest patch and it is working great for me. I used Intellij Idea with the Asciidoc Plugin. Differently from Olivier's observation, the main developer-manual ist updated when I make a change in developer-manual.adoc. Both html and pdf include the change. It is not updated when I only change an included document like accounting.adoc. I think it would be good to recreate all files if they have chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not be changed even if it is rewritten so it should be no problem. I think this is a good starting point, more pints might come up if we use it more intensely. Thanks, Michael Am 21.02.18 um 14:08 schrieb Olivier Heintz: Thank you for the work, Taher I have played with it and merge with my tests. Currently, I have start from Accounting_Agreement, convert from docbook and update and test renderer by both your gradle task and by AsciidocFx html button With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is not in the _include directory. Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure) it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one. The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory. The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation. Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-) Olivier Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: Hi Taher I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to d
Re: [Discussion] documentation framework for OFBiz
One of the design goals I had in mind is to make things publishable from the component as well as from the master manual. To do that, I need to think of a proper way for handling all kinds of artifacts like images, and sub-content. So I can't answer you immediately without some review first. I'll provide a patch as soon as I've figured it out. It's a bit tricky because the images directory shifts and is handled differently based on your location in the directory structure. On Sat, Feb 24, 2018 at 6:15 PM, Michael Brohl wrote: > Hi Taher, > > maybe it's enough to only define a convention, like an include directory > below each documentation folder? > > src / docs / asciidoc / includes > > ord maybe > > src / docs / includes > > if they should be reusable also with other documentation frameworks? > > > Am 24.02.18 um 16:12 schrieb Taher Alkhateeb: > >> I haven't yet setup the images variables yet, but it is relatively >> trivial. For now you can simply include using a relative directory >> format. I will update the PoC to include images >> >> On Sat, Feb 24, 2018 at 6:10 PM, Michael Brohl >> wrote: >>> >>> I have a question regarding included media files (images etc.) for >>> documentation. Where are they supposed to be stored? >>> >>> Regards, >>> >>> Michael Brohl >>> ecomify GmbH >>> www.ecomify.de >>> >>> >>> Am 24.02.18 um 15:44 schrieb Michael Brohl: >>> I have tried Taher's latest patch and it is working great for me. I used Intellij Idea with the Asciidoc Plugin. Differently from Olivier's observation, the main developer-manual ist updated when I make a change in developer-manual.adoc. Both html and pdf include the change. It is not updated when I only change an included document like accounting.adoc. I think it would be good to recreate all files if they have chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not be changed even if it is rewritten so it should be no problem. I think this is a good starting point, more pints might come up if we use it more intensely. Thanks, Michael Am 21.02.18 um 14:08 schrieb Olivier Heintz: > > Thank you for the work, Taher > > I have played with it and merge with my tests. > Currently, I have start from Accounting_Agreement, convert from docbook > and update and > test renderer by both your gradle task and by AsciidocFx html button > > With a lot of include, result html file would be very large and in some > case it will be good to be able to put a link in place > of include. Currenlty the generateOfbizDocumentation task doesn't > generate file for doc in component even if the adoc file is > not in the _include directory. > > Just for information: With AsciidocFx (I have understood it use > asciidoctor for generate html file, but I'm not sure) > it's not necessary to say include file is in _include directory, it > read > both in the current directory and in the _include one. > The generateOfbizDocumentation task doesn't use the same rule, we > should > say explicitly it's in the _include directory. > > The main "malfunction" of the generateOfbizDocumentation task is that > it > not re-generate the html file if it already exist > even if the main adoc file was modified. So it's needed to remove it > manually before call generateOfbizDocumentation. > > Thank you for your usage of leveloffset, it's generated by docbook > conversion, but now I understand how it works ;-) > > > Olivier > > Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : >> >> Hello documentation team and everyone >> >> I have created a slightly modified design of the documentation >> framework with some sample contents in [1]. I highlight the changes >> below: >> - Created a new top-level directory called "docs/asciidoc". The reason >> is so that we have more than one possible manual. >> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc >> - Created "Apache OFBiz Developer Manual" in >> docs/asciidoc/developer-manual.adoc >> - Created a sample document in the accounting component to show how >> documents are linked together. >> - Used a special directive called "leveloffset" in the include >> directive. This directive shifts the headers of the included document >> (H2 becomes H3, and so on) so that sub-sections can be published >> separately. >> - Created a task called generateOfbizDocumentation to generate the >> documentation (both PDF and HTML) for framework + core apps >> - Created a task called generatePluginDocumentation >> -PpluginId=whatever to generate the documentation for a single plugin. >> >> That's it. It's simple, easy to understand and I think you might like >> it. Any feedback is welcom
Re: [Discussion] documentation framework for OFBiz
Hi Taher, maybe it's enough to only define a convention, like an include directory below each documentation folder? src / docs / asciidoc / includes ord maybe src / docs / includes if they should be reusable also with other documentation frameworks? Am 24.02.18 um 16:12 schrieb Taher Alkhateeb: I haven't yet setup the images variables yet, but it is relatively trivial. For now you can simply include using a relative directory format. I will update the PoC to include images On Sat, Feb 24, 2018 at 6:10 PM, Michael Brohl wrote: I have a question regarding included media files (images etc.) for documentation. Where are they supposed to be stored? Regards, Michael Brohl ecomify GmbH www.ecomify.de Am 24.02.18 um 15:44 schrieb Michael Brohl: I have tried Taher's latest patch and it is working great for me. I used Intellij Idea with the Asciidoc Plugin. Differently from Olivier's observation, the main developer-manual ist updated when I make a change in developer-manual.adoc. Both html and pdf include the change. It is not updated when I only change an included document like accounting.adoc. I think it would be good to recreate all files if they have chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not be changed even if it is rewritten so it should be no problem. I think this is a good starting point, more pints might come up if we use it more intensely. Thanks, Michael Am 21.02.18 um 14:08 schrieb Olivier Heintz: Thank you for the work, Taher I have played with it and merge with my tests. Currently, I have start from Accounting_Agreement, convert from docbook and update and test renderer by both your gradle task and by AsciidocFx html button With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is not in the _include directory. Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure) it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one. The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory. The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation. Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-) Olivier Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: Hi Taher I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed. We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!). My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-) Thanks Sharan On 2018/01/28 10:12:41, Taher Alkhateeb wrote: Like Michael I think it is also a minor point. The reason I chose this structure is because it is the default one for asciidoctor and is flexible for the future, so Paul also makes a good point. Any structure is fine by me, the real important w
Re: [Discussion] documentation framework for OFBiz
I haven't yet setup the images variables yet, but it is relatively trivial. For now you can simply include using a relative directory format. I will update the PoC to include images On Sat, Feb 24, 2018 at 6:10 PM, Michael Brohl wrote: > I have a question regarding included media files (images etc.) for > documentation. Where are they supposed to be stored? > > Regards, > > Michael Brohl > ecomify GmbH > www.ecomify.de > > > Am 24.02.18 um 15:44 schrieb Michael Brohl: > >> I have tried Taher's latest patch and it is working great for me. I used >> Intellij Idea with the Asciidoc Plugin. >> >> Differently from Olivier's observation, the main developer-manual ist >> updated when I make a change in developer-manual.adoc. Both html and pdf >> include the change. >> >> It is not updated when I only change an included document like >> accounting.adoc. I think it would be good to recreate all files if they have >> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not >> be changed even if it is rewritten so it should be no problem. >> >> I think this is a good starting point, more pints might come up if we use >> it more intensely. >> >> Thanks, >> >> Michael >> >> >> Am 21.02.18 um 14:08 schrieb Olivier Heintz: >>> >>> Thank you for the work, Taher >>> >>> I have played with it and merge with my tests. >>> Currently, I have start from Accounting_Agreement, convert from docbook >>> and update and >>> test renderer by both your gradle task and by AsciidocFx html button >>> >>> With a lot of include, result html file would be very large and in some >>> case it will be good to be able to put a link in place >>> of include. Currenlty the generateOfbizDocumentation task doesn't >>> generate file for doc in component even if the adoc file is >>> not in the _include directory. >>> >>> Just for information: With AsciidocFx (I have understood it use >>> asciidoctor for generate html file, but I'm not sure) >>> it's not necessary to say include file is in _include directory, it read >>> both in the current directory and in the _include one. >>> The generateOfbizDocumentation task doesn't use the same rule, we should >>> say explicitly it's in the _include directory. >>> >>> The main "malfunction" of the generateOfbizDocumentation task is that it >>> not re-generate the html file if it already exist >>> even if the main adoc file was modified. So it's needed to remove it >>> manually before call generateOfbizDocumentation. >>> >>> Thank you for your usage of leveloffset, it's generated by docbook >>> conversion, but now I understand how it works ;-) >>> >>> >>> Olivier >>> >>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: > > Hi Taher > > I think a documentation team would be a great idea. There are people > that have indicated that they'd like to help out with documentation tasks > on > the user list so that is where I'd recruit some people from. As long as > people know what they need to do to create the patches then it will > become a > funnel process of getting it committed. > > We need a plan to consolidate the information sitting in the wiki and > getting it put into the documentation framework (and this work will then > significantly clear up the wiki!). > > My availability is pretty bad this week so hope to pick this up again > or start the recruitment campaign next week :-) > > Thanks > Sharan > > On 2018/01/28 10:12:41, Taher Alkhateeb > wrote: >> >> Like Michael I think it is also a minor point. The reason I chose this >>
Re: [Discussion] documentation framework for OFBiz
I have a question regarding included media files (images etc.) for documentation. Where are they supposed to be stored? Regards, Michael Brohl ecomify GmbH www.ecomify.de Am 24.02.18 um 15:44 schrieb Michael Brohl: I have tried Taher's latest patch and it is working great for me. I used Intellij Idea with the Asciidoc Plugin. Differently from Olivier's observation, the main developer-manual ist updated when I make a change in developer-manual.adoc. Both html and pdf include the change. It is not updated when I only change an included document like accounting.adoc. I think it would be good to recreate all files if they have chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not be changed even if it is rewritten so it should be no problem. I think this is a good starting point, more pints might come up if we use it more intensely. Thanks, Michael Am 21.02.18 um 14:08 schrieb Olivier Heintz: Thank you for the work, Taher I have played with it and merge with my tests. Currently, I have start from Accounting_Agreement, convert from docbook and update and test renderer by both your gradle task and by AsciidocFx html button With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is not in the _include directory. Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure) it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one. The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory. The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation. Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-) Olivier Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: Hi Taher I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed. We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!). My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-) Thanks Sharan On 2018/01/28 10:12:41, Taher Alkhateeb wrote: Like Michael I think it is also a minor point. The reason I chose this structure is because it is the default one for asciidoctor and is flexible for the future, so Paul also makes a good point. Any structure is fine by me, the real important work is getting the documentation right which is very exciting to me. I will create a patch soon for a base level structure and publishing options for both HTML and PDF. It would be fantastic if we can unify _all_ of our documentation here including stuff currently in the wiki. This way any changes to code are reflected (probably in the same commit) with the relevant documentation. I think we should start to consider maybe forming a team willing to help. This is a big, but extremely importan
Re: [Discussion] documentation framework for OFBiz
I have tried Taher's latest patch and it is working great for me. I used Intellij Idea with the Asciidoc Plugin. Differently from Olivier's observation, the main developer-manual ist updated when I make a change in developer-manual.adoc. Both html and pdf include the change. It is not updated when I only change an included document like accounting.adoc. I think it would be good to recreate all files if they have chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not be changed even if it is rewritten so it should be no problem. I think this is a good starting point, more pints might come up if we use it more intensely. Thanks, Michael Am 21.02.18 um 14:08 schrieb Olivier Heintz: Thank you for the work, Taher I have played with it and merge with my tests. Currently, I have start from Accounting_Agreement, convert from docbook and update and test renderer by both your gradle task and by AsciidocFx html button With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is not in the _include directory. Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure) it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one. The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory. The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation. Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-) Olivier Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: Hi Taher I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed. We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!). My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-) Thanks Sharan On 2018/01/28 10:12:41, Taher Alkhateeb wrote: Like Michael I think it is also a minor point. The reason I chose this structure is because it is the default one for asciidoctor and is flexible for the future, so Paul also makes a good point. Any structure is fine by me, the real important work is getting the documentation right which is very exciting to me. I will create a patch soon for a base level structure and publishing options for both HTML and PDF. It would be fantastic if we can unify _all_ of our documentation here including stuff currently in the wiki. This way any changes to code are reflected (probably in the same commit) with the relevant documentation. I think we should start to consider maybe forming a team willing to help. This is a big, but extremely important thing to have. If we do this right then I think adoption rates would increase and our community would get larger. On Jan 28, 2018 12:19 PM, "Michael Brohl" wrote: Hi Paul, this is only a minor point for me, it just saves one folder/struc
Re: [Discussion] documentation framework for OFBiz
Thank you for the work, Taher I have played with it and merge with my tests. Currently, I have start from Accounting_Agreement, convert from docbook and update and test renderer by both your gradle task and by AsciidocFx html button With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is not in the _include directory. Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure) it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one. The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory. The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation. Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-) Olivier Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit : > Hello documentation team and everyone > > I have created a slightly modified design of the documentation > framework with some sample contents in [1]. I highlight the changes > below: > - Created a new top-level directory called "docs/asciidoc". The reason > is so that we have more than one possible manual. > - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc > - Created "Apache OFBiz Developer Manual" in > docs/asciidoc/developer-manual.adoc > - Created a sample document in the accounting component to show how > documents are linked together. > - Used a special directive called "leveloffset" in the include > directive. This directive shifts the headers of the included document > (H2 becomes H3, and so on) so that sub-sections can be published > separately. > - Created a task called generateOfbizDocumentation to generate the > documentation (both PDF and HTML) for framework + core apps > - Created a task called generatePluginDocumentation > -PpluginId=whatever to generate the documentation for a single plugin. > > That's it. It's simple, easy to understand and I think you might like > it. Any feedback is welcome, and I'll talk to you soon over Skype. > > [1] https://issues.apache.org/jira/browse/OFBIZ-9873 > > On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: >> Hi Taher >> >> I think a documentation team would be a great idea. There are people that >> have indicated that they'd like to help out with documentation tasks on the >> user list so that is where I'd recruit some people from. As long as people >> know what they need to do to create the patches then it will become a funnel >> process of getting it committed. >> >> We need a plan to consolidate the information sitting in the wiki and >> getting it put into the documentation framework (and this work will then >> significantly clear up the wiki!). >> >> My availability is pretty bad this week so hope to pick this up again or >> start the recruitment campaign next week :-) >> >> Thanks >> Sharan >> >> On 2018/01/28 10:12:41, Taher Alkhateeb wrote: >>> Like Michael I think it is also a minor point. The reason I chose this >>> structure is because it is the default one for asciidoctor and is flexible >>> for the future, so Paul also makes a good point. Any structure is fine by >>> me, the real important work is getting the documentation right which is >>> very exciting to me. >>> >>> I will create a patch soon for a base level structure and publishing >>> options for both HTML and PDF. It would be fantastic if we can unify _all_ >>> of our documentation here including stuff currently in the wiki. This way >>> any changes to code are reflected (probably in the same commit) with the >>> relevant documentation. >>> >>> I think we should start to consider maybe forming a team willing to help. >>> This is a big, but extremely important thing to have. If we do this right >>> then I think adoption rates would increase and our community would get >>> larger. >>> >>> On Jan 28, 2018 12:19 PM, "Michael Brohl" wrote: >>> >>> Hi Paul, >>> >>> this is only a minor point for me, it just saves one folder/structure level. >>> >>> If we want to stay open for other documentation frameworks in the future, >>> it might be better to keep the proposed structure. >>> >>> Best regards, >>> >>> Michael >>> >>> >>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy: >>> >>> On 26 January 2018 at 19:53, Michael Brohl wrote: with a small modification: I don't think we'll need a two-folder structure > /docs/asciidoc, only /docs should be sufficient, no? > > Hi Michael, We have streamlined the build system in other places by
Re: [Discussion] documentation framework for OFBiz
Great work, Taher, thank you for the example setup. I'm going to play with it in the next days and provide my feedback. Thanks, Michael Am 20.02.18 um 17:48 schrieb Taher Alkhateeb: Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: Hi Taher I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed. We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!). My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-) Thanks Sharan On 2018/01/28 10:12:41, Taher Alkhateeb wrote: Like Michael I think it is also a minor point. The reason I chose this structure is because it is the default one for asciidoctor and is flexible for the future, so Paul also makes a good point. Any structure is fine by me, the real important work is getting the documentation right which is very exciting to me. I will create a patch soon for a base level structure and publishing options for both HTML and PDF. It would be fantastic if we can unify _all_ of our documentation here including stuff currently in the wiki. This way any changes to code are reflected (probably in the same commit) with the relevant documentation. I think we should start to consider maybe forming a team willing to help. This is a big, but extremely important thing to have. If we do this right then I think adoption rates would increase and our community would get larger. On Jan 28, 2018 12:19 PM, "Michael Brohl" wrote: Hi Paul, this is only a minor point for me, it just saves one folder/structure level. If we want to stay open for other documentation frameworks in the future, it might be better to keep the proposed structure. Best regards, Michael Am 28.01.18 um 02:54 schrieb Paul Foxworthy: On 26 January 2018 at 19:53, Michael Brohl wrote: with a small modification: I don't think we'll need a two-folder structure /docs/asciidoc, only /docs should be sufficient, no? Hi Michael, We have streamlined the build system in other places by having folders for the source language: groovyScripts, minilang, src/main/java . It means Groovy and other build tools can have default rules for what to do with the contents of a language folder, and allows for the possibility of other languages in future if necessary. The extra layer is only a minor nuisance. I think I'd prefer to keep it. What do you see as the disadvantages? Cheers Paul Foxworthy smime.p7s Description: S/MIME Cryptographic Signature
Re: [Discussion] documentation framework for OFBiz
Hi Taher Thanks for the update. I'll try and take a look at this later today. Thanks Sharan On 2018/02/20 16:48:13, Taher Alkhateeb wrote: > Hello documentation team and everyone > > I have created a slightly modified design of the documentation > framework with some sample contents in [1]. I highlight the changes > below: > - Created a new top-level directory called "docs/asciidoc". The reason > is so that we have more than one possible manual. > - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc > - Created "Apache OFBiz Developer Manual" in > docs/asciidoc/developer-manual.adoc > - Created a sample document in the accounting component to show how > documents are linked together. > - Used a special directive called "leveloffset" in the include > directive. This directive shifts the headers of the included document > (H2 becomes H3, and so on) so that sub-sections can be published > separately. > - Created a task called generateOfbizDocumentation to generate the > documentation (both PDF and HTML) for framework + core apps > - Created a task called generatePluginDocumentation > -PpluginId=whatever to generate the documentation for a single plugin. > > That's it. It's simple, easy to understand and I think you might like > it. Any feedback is welcome, and I'll talk to you soon over Skype. > > [1] https://issues.apache.org/jira/browse/OFBIZ-9873 > > On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: > > Hi Taher > > > > I think a documentation team would be a great idea. There are people that > > have indicated that they'd like to help out with documentation tasks on the > > user list so that is where I'd recruit some people from. As long as people > > know what they need to do to create the patches then it will become a > > funnel process of getting it committed. > > > > We need a plan to consolidate the information sitting in the wiki and > > getting it put into the documentation framework (and this work will then > > significantly clear up the wiki!). > > > > My availability is pretty bad this week so hope to pick this up again or > > start the recruitment campaign next week :-) > > > > Thanks > > Sharan > > > > On 2018/01/28 10:12:41, Taher Alkhateeb wrote: > >> Like Michael I think it is also a minor point. The reason I chose this > >> structure is because it is the default one for asciidoctor and is flexible > >> for the future, so Paul also makes a good point. Any structure is fine by > >> me, the real important work is getting the documentation right which is > >> very exciting to me. > >> > >> I will create a patch soon for a base level structure and publishing > >> options for both HTML and PDF. It would be fantastic if we can unify _all_ > >> of our documentation here including stuff currently in the wiki. This way > >> any changes to code are reflected (probably in the same commit) with the > >> relevant documentation. > >> > >> I think we should start to consider maybe forming a team willing to help. > >> This is a big, but extremely important thing to have. If we do this right > >> then I think adoption rates would increase and our community would get > >> larger. > >> > >> On Jan 28, 2018 12:19 PM, "Michael Brohl" wrote: > >> > >> Hi Paul, > >> > >> this is only a minor point for me, it just saves one folder/structure > >> level. > >> > >> If we want to stay open for other documentation frameworks in the future, > >> it might be better to keep the proposed structure. > >> > >> Best regards, > >> > >> Michael > >> > >> > >> Am 28.01.18 um 02:54 schrieb Paul Foxworthy: > >> > >> On 26 January 2018 at 19:53, Michael Brohl > >> wrote: > >> > > >> > > >> > with a small modification: I don't think we'll need a two-folder > >> > structure > >> >> /docs/asciidoc, only /docs should be sufficient, no? > >> >> > >> >> Hi Michael, > >> > > >> > We have streamlined the build system in other places by having folders > >> > for > >> > the source language: groovyScripts, minilang, src/main/java . > >> > > >> > It means Groovy and other build tools can have default rules for what to > >> > do > >> > with the contents of a language folder, and allows for the possibility of > >> > other languages in future if necessary. > >> > > >> > The extra layer is only a minor nuisance. I think I'd prefer to keep it. > >> > What do you see as the disadvantages? > >> > > >> > Cheers > >> > > >> > Paul Foxworthy > >> > > >> > > >> >
Re: [Discussion] documentation framework for OFBiz
Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin. That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga wrote: > Hi Taher > > I think a documentation team would be a great idea. There are people that > have indicated that they'd like to help out with documentation tasks on the > user list so that is where I'd recruit some people from. As long as people > know what they need to do to create the patches then it will become a funnel > process of getting it committed. > > We need a plan to consolidate the information sitting in the wiki and getting > it put into the documentation framework (and this work will then > significantly clear up the wiki!). > > My availability is pretty bad this week so hope to pick this up again or > start the recruitment campaign next week :-) > > Thanks > Sharan > > On 2018/01/28 10:12:41, Taher Alkhateeb wrote: >> Like Michael I think it is also a minor point. The reason I chose this >> structure is because it is the default one for asciidoctor and is flexible >> for the future, so Paul also makes a good point. Any structure is fine by >> me, the real important work is getting the documentation right which is >> very exciting to me. >> >> I will create a patch soon for a base level structure and publishing >> options for both HTML and PDF. It would be fantastic if we can unify _all_ >> of our documentation here including stuff currently in the wiki. This way >> any changes to code are reflected (probably in the same commit) with the >> relevant documentation. >> >> I think we should start to consider maybe forming a team willing to help. >> This is a big, but extremely important thing to have. If we do this right >> then I think adoption rates would increase and our community would get >> larger. >> >> On Jan 28, 2018 12:19 PM, "Michael Brohl" wrote: >> >> Hi Paul, >> >> this is only a minor point for me, it just saves one folder/structure level. >> >> If we want to stay open for other documentation frameworks in the future, >> it might be better to keep the proposed structure. >> >> Best regards, >> >> Michael >> >> >> Am 28.01.18 um 02:54 schrieb Paul Foxworthy: >> >> On 26 January 2018 at 19:53, Michael Brohl wrote: >> > >> > >> > with a small modification: I don't think we'll need a two-folder structure >> >> /docs/asciidoc, only /docs should be sufficient, no? >> >> >> >> Hi Michael, >> > >> > We have streamlined the build system in other places by having folders for >> > the source language: groovyScripts, minilang, src/main/java . >> > >> > It means Groovy and other build tools can have default rules for what to do >> > with the contents of a language folder, and allows for the possibility of >> > other languages in future if necessary. >> > >> > The extra layer is only a minor nuisance. I think I'd prefer to keep it. >> > What do you see as the disadvantages? >> > >> > Cheers >> > >> > Paul Foxworthy >> > >> > >>
Re: [Discussion] documentation framework for OFBiz
Hi Taher I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed. We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!). My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-) Thanks Sharan On 2018/01/28 10:12:41, Taher Alkhateeb wrote: > Like Michael I think it is also a minor point. The reason I chose this > structure is because it is the default one for asciidoctor and is flexible > for the future, so Paul also makes a good point. Any structure is fine by > me, the real important work is getting the documentation right which is > very exciting to me. > > I will create a patch soon for a base level structure and publishing > options for both HTML and PDF. It would be fantastic if we can unify _all_ > of our documentation here including stuff currently in the wiki. This way > any changes to code are reflected (probably in the same commit) with the > relevant documentation. > > I think we should start to consider maybe forming a team willing to help. > This is a big, but extremely important thing to have. If we do this right > then I think adoption rates would increase and our community would get > larger. > > On Jan 28, 2018 12:19 PM, "Michael Brohl" wrote: > > Hi Paul, > > this is only a minor point for me, it just saves one folder/structure level. > > If we want to stay open for other documentation frameworks in the future, > it might be better to keep the proposed structure. > > Best regards, > > Michael > > > Am 28.01.18 um 02:54 schrieb Paul Foxworthy: > > On 26 January 2018 at 19:53, Michael Brohl wrote: > > > > > > with a small modification: I don't think we'll need a two-folder structure > >> /docs/asciidoc, only /docs should be sufficient, no? > >> > >> Hi Michael, > > > > We have streamlined the build system in other places by having folders for > > the source language: groovyScripts, minilang, src/main/java . > > > > It means Groovy and other build tools can have default rules for what to do > > with the contents of a language folder, and allows for the possibility of > > other languages in future if necessary. > > > > The extra layer is only a minor nuisance. I think I'd prefer to keep it. > > What do you see as the disadvantages? > > > > Cheers > > > > Paul Foxworthy > > > > >
Re: [Discussion] documentation framework for OFBiz
\o/ Jacques Le 28/01/2018 à 11:12, Taher Alkhateeb a écrit : Like Michael I think it is also a minor point. The reason I chose this structure is because it is the default one for asciidoctor and is flexible for the future, so Paul also makes a good point. Any structure is fine by me, the real important work is getting the documentation right which is very exciting to me. I will create a patch soon for a base level structure and publishing options for both HTML and PDF. It would be fantastic if we can unify _all_ of our documentation here including stuff currently in the wiki. This way any changes to code are reflected (probably in the same commit) with the relevant documentation. I think we should start to consider maybe forming a team willing to help. This is a big, but extremely important thing to have. If we do this right then I think adoption rates would increase and our community would get larger. On Jan 28, 2018 12:19 PM, "Michael Brohl" wrote: Hi Paul, this is only a minor point for me, it just saves one folder/structure level. If we want to stay open for other documentation frameworks in the future, it might be better to keep the proposed structure. Best regards, Michael Am 28.01.18 um 02:54 schrieb Paul Foxworthy: On 26 January 2018 at 19:53, Michael Brohl wrote: with a small modification: I don't think we'll need a two-folder structure /docs/asciidoc, only /docs should be sufficient, no? Hi Michael, We have streamlined the build system in other places by having folders for the source language: groovyScripts, minilang, src/main/java . It means Groovy and other build tools can have default rules for what to do with the contents of a language folder, and allows for the possibility of other languages in future if necessary. The extra layer is only a minor nuisance. I think I'd prefer to keep it. What do you see as the disadvantages? Cheers Paul Foxworthy
Re: [Discussion] documentation framework for OFBiz
Like Michael I think it is also a minor point. The reason I chose this structure is because it is the default one for asciidoctor and is flexible for the future, so Paul also makes a good point. Any structure is fine by me, the real important work is getting the documentation right which is very exciting to me. I will create a patch soon for a base level structure and publishing options for both HTML and PDF. It would be fantastic if we can unify _all_ of our documentation here including stuff currently in the wiki. This way any changes to code are reflected (probably in the same commit) with the relevant documentation. I think we should start to consider maybe forming a team willing to help. This is a big, but extremely important thing to have. If we do this right then I think adoption rates would increase and our community would get larger. On Jan 28, 2018 12:19 PM, "Michael Brohl" wrote: Hi Paul, this is only a minor point for me, it just saves one folder/structure level. If we want to stay open for other documentation frameworks in the future, it might be better to keep the proposed structure. Best regards, Michael Am 28.01.18 um 02:54 schrieb Paul Foxworthy: On 26 January 2018 at 19:53, Michael Brohl wrote: > > > with a small modification: I don't think we'll need a two-folder structure >> /docs/asciidoc, only /docs should be sufficient, no? >> >> Hi Michael, > > We have streamlined the build system in other places by having folders for > the source language: groovyScripts, minilang, src/main/java . > > It means Groovy and other build tools can have default rules for what to do > with the contents of a language folder, and allows for the possibility of > other languages in future if necessary. > > The extra layer is only a minor nuisance. I think I'd prefer to keep it. > What do you see as the disadvantages? > > Cheers > > Paul Foxworthy > >
Re: [Discussion] documentation framework for OFBiz
Hi Paul, this is only a minor point for me, it just saves one folder/structure level. If we want to stay open for other documentation frameworks in the future, it might be better to keep the proposed structure. Best regards, Michael Am 28.01.18 um 02:54 schrieb Paul Foxworthy: On 26 January 2018 at 19:53, Michael Brohl wrote: with a small modification: I don't think we'll need a two-folder structure /docs/asciidoc, only /docs should be sufficient, no? Hi Michael, We have streamlined the build system in other places by having folders for the source language: groovyScripts, minilang, src/main/java . It means Groovy and other build tools can have default rules for what to do with the contents of a language folder, and allows for the possibility of other languages in future if necessary. The extra layer is only a minor nuisance. I think I'd prefer to keep it. What do you see as the disadvantages? Cheers Paul Foxworthy smime.p7s Description: S/MIME Cryptographic Signature
Re: [Discussion] documentation framework for OFBiz
On 26 January 2018 at 19:53, Michael Brohl wrote: > with a small modification: I don't think we'll need a two-folder structure > /docs/asciidoc, only /docs should be sufficient, no? > Hi Michael, We have streamlined the build system in other places by having folders for the source language: groovyScripts, minilang, src/main/java . It means Groovy and other build tools can have default rules for what to do with the contents of a language folder, and allows for the possibility of other languages in future if necessary. The extra layer is only a minor nuisance. I think I'd prefer to keep it. What do you see as the disadvantages? Cheers Paul Foxworthy -- Coherent Software Australia Pty Ltd PO Box 2773 Cheltenham Vic 3192 Australia Phone: +61 3 9585 6788 Web: http://www.coherentsoftware.com.au/ Email: i...@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
+1 with a small modification: I don't think we'll need a two-folder structure /docs/asciidoc, only /docs should be sufficient, no? Regards, Michael Am 25.01.18 um 15:00 schrieb Sharan Foga: Hi Taher The picture helps :-) I had to do a bit of a double-take but I get it now and a big +1 I like what you are suggesting – very nice. It is not entirely following the menu structure (which is good) instead it is looking at the individual topics. This means that we can make the main document flow a lot easier than simply following what we have in the menus. (e.g We know that you can get to the same place from by different routes on the menus and screens, so focussing on the topic itself will help that.) I think this will give us the flexibility we need. A standard structure helps people know where to put things. Thanks Sharan On 2018/01/25 11:37:02, Taher Alkhateeb wrote: Hi Everyone, So after a little bit of thinking, I came up with an example file structure for OFBiz documentation which is listed below. The full OFBiz manual simply points to all the parts in applications, framework, and themes to complete the documentation. Any ideas or feedback is welcomed. A few points to note: - Gradle by default ignores any files in the _include sub directory and so it will only publish the outer document. - This way, we can publish per component (in isolation) or the whole documentation by simply publishing the ofbiz-manual.adoc file - We can further branch out the documentation as needed. ofbiz ├── applications │ ├── accounting │ │ └── src │ │ └── docs │ │ └── asciidoc │ │ ├── accounting.adoc │ │ └── _include │ │ ├── accounting-intro.adoc │ │ ├── budgets.adoc │ │ ├── invoices.adoc │ │ ├── payments.adoc │ │ └── understanding-general-ledger.adoc │ └── humanres │ └── src │ └── docs │ └── asciidoc │ ├── humanres.adoc │ └── _include │ ├── employee-evaluations.adoc │ ├── human-resources-intro.adoc │ └── punch-in-punch-out.adoc ├── framework │ ├── base │ │ └── src │ │ └── docs │ │ └── asciidoc │ │ ├── base.adoc │ │ └── _include │ │ ├── containers.adoc │ │ ├── framework-intro.adoc │ │ └── loading-components.adoc │ ├── entity │ │ └── src │ │ └── docs │ │ └── asciidoc │ │ ├── entity.adoc │ │ └── _include │ │ ├── entity-conditions-api.adoc │ │ ├── entity-engine-intro.adoc │ │ └── mapping-new-database.adoc │ └── widget │ └── src │ └── docs │ └── asciidoc │ ├── _include │ │ ├── form-widgets.adoc │ │ ├── screen-widgets.adoc │ │ └── widget-system-intro.adoc │ └── widget.adoc ├── ofbiz-manual.adoc ├── plugins │ └── example │ └── src │ └── docs │ └── asciidoc │ ├── example.adoc │ └── _include │ ├── example-intro.adoc │ └── extending-example-widgets.adoc └── themes └── common-theme └── src └── docs └── asciidoc ├── common-theme.adoc └── _include ├── ofbiz-themes-intro.adoc ├── web-assets.adoc └── why-common-theme.adoc On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux wrote: Hi Sharan, Craig, We already have a document that consolidates many smaller documents into itself, but as said Sharan in another reply it got not much attention because it was maybe not statisfying (though had interesting info) https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML My 2cts Jacques Le 18/01/2018 à 13:31, Sharan Foga a écrit : Hi Craig Generally I was thinking about how it was going to be laid out. So if you think about one big consolidated OFBiz Guide that contains both technical and user guide info, then what would that l
Re: [Discussion] documentation framework for OFBiz
Hi Taher The picture helps :-) I had to do a bit of a double-take but I get it now and a big +1 I like what you are suggesting â very nice. It is not entirely following the menu structure (which is good) instead it is looking at the individual topics. This means that we can make the main document flow a lot easier than simply following what we have in the menus. (e.g We know that you can get to the same place from by different routes on the menus and screens, so focussing on the topic itself will help that.) I think this will give us the flexibility we need. A standard structure helps people know where to put things. Thanks Sharan On 2018/01/25 11:37:02, Taher Alkhateeb wrote: > Hi Everyone, > > So after a little bit of thinking, I came up with an example file > structure for OFBiz documentation which is listed below. The full > OFBiz manual simply points to all the parts in applications, > framework, and themes to complete the documentation. Any ideas or > feedback is welcomed. > > A few points to note: > - Gradle by default ignores any files in the _include sub directory > and so it will only publish the outer document. > - This way, we can publish per component (in isolation) or the whole > documentation by simply publishing the ofbiz-manual.adoc file > - We can further branch out the documentation as needed. > > ofbiz > âââ applications > â âââ accounting > â â âââ src > â â âââ docs > â â âââ asciidoc > â â âââ accounting.adoc > â â âââ _include > â â âââ accounting-intro.adoc > â â âââ budgets.adoc > â â âââ invoices.adoc > â â âââ payments.adoc > â â âââ understanding-general-ledger.adoc > â âââ humanres > â âââ src > â âââ docs > â âââ asciidoc > â âââ humanres.adoc > â âââ _include > â âââ employee-evaluations.adoc > â âââ human-resources-intro.adoc > â âââ punch-in-punch-out.adoc > âââ framework > â âââ base > â â âââ src > â â âââ docs > â â âââ asciidoc > â â âââ base.adoc > â â âââ _include > â â âââ containers.adoc > â â âââ framework-intro.adoc > â â âââ loading-components.adoc > â âââ entity > â â âââ src > â â âââ docs > â â âââ asciidoc > â â âââ entity.adoc > â â âââ _include > â â âââ entity-conditions-api.adoc > â â âââ entity-engine-intro.adoc > â â âââ mapping-new-database.adoc > â âââ widget > â âââ src > â âââ docs > â âââ asciidoc > â âââ _include > â â âââ form-widgets.adoc > â â âââ screen-widgets.adoc > â â âââ widget-system-intro.adoc > â âââ widget.adoc > âââ ofbiz-manual.adoc > âââ plugins > â âââ example > â âââ src > â âââ docs > â âââ asciidoc > â âââ example.adoc > â âââ _include > â âââ example-intro.adoc > â âââ extending-example-widgets.adoc > âââ themes > âââ common-theme > âââ src > âââ docs > âââ asciidoc > âââ common-theme.adoc > âââ _include > âââ ofbiz-themes-intro.adoc > âââ web-assets.adoc > âââ why-common-theme.adoc > > On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux > wrote: > > Hi Sharan, Craig, > > > > We already have a document that consolidates many smaller documents into > > itself, but as said Sharan in another reply it got not much attention > > because it was maybe not statisfying (though had interesting info) > > > > https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML > > > > My 2cts > > > > Jacques > > > > > > > > Le 18/01/2018 à 13:31, Sharan Foga a écrit : > >> > >> Hi Craig > >> > >> Generally I was thinking about how it was going to be laid out. So if you > >> think about one big consolidated OFBiz Guide that contains both technical
Re: [Discussion] documentation framework for OFBiz
Hi Everyone, So after a little bit of thinking, I came up with an example file structure for OFBiz documentation which is listed below. The full OFBiz manual simply points to all the parts in applications, framework, and themes to complete the documentation. Any ideas or feedback is welcomed. A few points to note: - Gradle by default ignores any files in the _include sub directory and so it will only publish the outer document. - This way, we can publish per component (in isolation) or the whole documentation by simply publishing the ofbiz-manual.adoc file - We can further branch out the documentation as needed. ofbiz ├── applications │ ├── accounting │ │ └── src │ │ └── docs │ │ └── asciidoc │ │ ├── accounting.adoc │ │ └── _include │ │ ├── accounting-intro.adoc │ │ ├── budgets.adoc │ │ ├── invoices.adoc │ │ ├── payments.adoc │ │ └── understanding-general-ledger.adoc │ └── humanres │ └── src │ └── docs │ └── asciidoc │ ├── humanres.adoc │ └── _include │ ├── employee-evaluations.adoc │ ├── human-resources-intro.adoc │ └── punch-in-punch-out.adoc ├── framework │ ├── base │ │ └── src │ │ └── docs │ │ └── asciidoc │ │ ├── base.adoc │ │ └── _include │ │ ├── containers.adoc │ │ ├── framework-intro.adoc │ │ └── loading-components.adoc │ ├── entity │ │ └── src │ │ └── docs │ │ └── asciidoc │ │ ├── entity.adoc │ │ └── _include │ │ ├── entity-conditions-api.adoc │ │ ├── entity-engine-intro.adoc │ │ └── mapping-new-database.adoc │ └── widget │ └── src │ └── docs │ └── asciidoc │ ├── _include │ │ ├── form-widgets.adoc │ │ ├── screen-widgets.adoc │ │ └── widget-system-intro.adoc │ └── widget.adoc ├── ofbiz-manual.adoc ├── plugins │ └── example │ └── src │ └── docs │ └── asciidoc │ ├── example.adoc │ └── _include │ ├── example-intro.adoc │ └── extending-example-widgets.adoc └── themes └── common-theme └── src └── docs └── asciidoc ├── common-theme.adoc └── _include ├── ofbiz-themes-intro.adoc ├── web-assets.adoc └── why-common-theme.adoc On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux wrote: > Hi Sharan, Craig, > > We already have a document that consolidates many smaller documents into > itself, but as said Sharan in another reply it got not much attention > because it was maybe not statisfying (though had interesting info) > > https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML > > My 2cts > > Jacques > > > > Le 18/01/2018 à 13:31, Sharan Foga a écrit : >> >> Hi Craig >> >> Generally I was thinking about how it was going to be laid out. So if you >> think about one big consolidated OFBiz Guide that contains both technical >> and user guide info, then what would that look like? How would you structure >> the one consolidated output? >> >> I don't think that it would necessarily need to mirror the exact structure >> of the menus - it just depends on how it's linked to the overall process (if >> you are thinking user docs). Also some of the things we need to write about >> won't appear anywhere in the menus - so we'll need a general place for that. >> >> My comment was also about the format of each of the source documents to >> ensure consistency. Since we are going to be consolidating many smaller >> documents into one big one, so it needs to look like they belong together. >> >> Hope that makes it clearer. >> >> Thanks >> Sharan >> >> On 2018-01-17 16:08, Craig Parker 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 aro
Re: [Discussion] documentation framework for OFBiz
Hi Sharan, Craig, We already have a document that consolidates many smaller documents into itself, but as said Sharan in another reply it got not much attention because it was maybe not statisfying (though had interesting info) https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML My 2cts Jacques Le 18/01/2018 à 13:31, Sharan Foga a écrit : Hi Craig Generally I was thinking about how it was going to be laid out. So if you think about one big consolidated OFBiz Guide that contains both technical and user guide info, then what would that look like? How would you structure the one consolidated output? I don't think that it would necessarily need to mirror the exact structure of the menus - it just depends on how it's linked to the overall process (if you are thinking user docs). Also some of the things we need to write about won't appear anywhere in the menus - so we'll need a general place for that. My comment was also about the format of each of the source documents to ensure consistency. Since we are going to be consolidating many smaller documents into one big one, so it needs to look like they belong together. Hope that makes it clearer. Thanks Sharan On 2018-01-17 16:08, Craig Parker 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" 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 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 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
Re: [Discussion] documentation framework for OFBiz
Inline... Le 18/01/2018 à 13:54, Sharan Foga a écrit : Hi Taher I've included some comments inline. On 2018-01-17 16:54, Taher Alkhateeb 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 I like this as it is a simple and easy way for us to do our first split. In the past we have tried to put everything together in a way that doesn't really fit, so doing an initial is it this or that, makes it a lot easier. +1 - 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. I like the idea of only one publishable document per component. That means that we have a fixed scope for what the documentation needs to cover (so no documentation creep). I'm sure we will get interlinking between components so can plan for it and link when ready. +1 and +1 for inter-links idea - 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. I'm not sure this can be called general documentation. I was thinking at another place initially, one place where people should look intuitively, like a documentation sub-dir of root. But we need to define what we call general documentation. - 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 As long as people can easily navigate it and find what they want quickly then one document could be the solution. At least we can start with that and if does start to become too heavy then look at re-arranging it or splitting it up. That sounds like a good idea, finding an ofbiz-documentation.adoc file is as easy as finding a documentation sub-dir of root. But then we need to remember that it's not often the content that confuse people but how to access it. So we need to think about the structure of this document (like separating end users and technical doc at the 1st level. Maybe we can think about having end users and technical doc separated in component? In the past I think all the details from the online help were published as a consolidated html file via the OFBiz cms. I think it was too linked to the individual screens so as standalone document without the screens, it wasn't as useful as it could be. I think people were also not much aware of this document, so it got not much critics and was not improved - 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. +1 on this. We will have to maintain the official plugin documentation, and I would see that people writing their own plugins can use this same mechanism to include their specific documentation. Sure +1! - 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. As per your later response, I think we could reduce the gradle tasks to one for the framework+core application docs and one for the plugins. Thanks for sharing - you have some good ideas here. Let's keep the discussion going :-) so anyone with other ideas, comments and feedback, please feel free to join the conversation. I agree, let's continue to share :) Jacques Thanks Sharan 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 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 ou
Re: [Discussion] documentation framework for OFBiz
Hi Taher I've included some comments inline. On 2018-01-17 16:54, Taher Alkhateeb 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 I like this as it is a simple and easy way for us to do our first split. In the past we have tried to put everything together in a way that doesn't really fit, so doing an initial is it this or that, makes it a lot easier. > - 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. I like the idea of only one publishable document per component. That means that we have a fixed scope for what the documentation needs to cover (so no documentation creep). I'm sure we will get interlinking between components so can plan for it and link when ready. > - 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 As long as people can easily navigate it and find what they want quickly then one document could be the solution. At least we can start with that and if does start to become too heavy then look at re-arranging it or splitting it up. In the past I think all the details from the online help were published as a consolidated html file via the OFBiz cms. I think it was too linked to the individual screens so as standalone document without the screens, it wasn't as useful as it could be. > - 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. +1 on this. We will have to maintain the official plugin documentation, and I would see that people writing their own plugins can use this same mechanism to include their specific documentation. > - 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. > As per your later response, I think we could reduce the gradle tasks to one for the framework+core application docs and one for the plugins. Thanks for sharing - you have some good ideas here. Let's keep the discussion going :-) so anyone with other ideas, comments and feedback, please feel free to join the conversation. Thanks Sharan > 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 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" 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 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
Re: [Discussion] documentation framework for OFBiz
Hi Craig Generally I was thinking about how it was going to be laid out. So if you think about one big consolidated OFBiz Guide that contains both technical and user guide info, then what would that look like? How would you structure the one consolidated output? I don't think that it would necessarily need to mirror the exact structure of the menus - it just depends on how it's linked to the overall process (if you are thinking user docs). Also some of the things we need to write about won't appear anywhere in the menus - so we'll need a general place for that. My comment was also about the format of each of the source documents to ensure consistency. Since we are going to be consolidating many smaller documents into one big one, so it needs to look like they belong together. Hope that makes it clearer. Thanks Sharan On 2018-01-17 16:08, Craig Parker 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" 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 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 > >>> 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 > >
Re: [Discussion] documentation framework for OFBiz
I'm not sure, but I think we should document "everything" like user, developer, etc. It's up to all of us to decide and I have no strong opinion on this. On Wed, Jan 17, 2018 at 6:56 PM, Craig Parker wrote: > And I'm just realizing... You're not talking end user docs are you? > > > > On 01/17/2018 10:54 AM, Taher Alkhateeb 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 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" 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 > 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 >> 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 document
Re: [Discussion] documentation framework for OFBiz
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 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 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" 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 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 > 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 e
Re: [Discussion] documentation framework for OFBiz
And I'm just realizing... You're not talking end user docs are you? On 01/17/2018 10:54 AM, Taher Alkhateeb 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 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" 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 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 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
Re: [Discussion] documentation framework for OFBiz
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 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" 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 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 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
Re: [Discussion] documentation framework for OFBiz
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" 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 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 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
Re: [Discussion] documentation framework for OFBiz
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" 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 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 > > 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 > > >
Re: [Discussion] documentation framework for OFBiz
:D indeed ! I will try it out tonight ! Gil On 15/01/2018 09:27, Taher Alkhateeb wrote: 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 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 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
Re: [Discussion] documentation framework for OFBiz
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 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 >> 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 > >
Re: [Discussion] documentation framework for OFBiz
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 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
Re: [Discussion] documentation framework for OFBiz
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 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 > 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 >
Re: [Discussion] documentation framework for OFBiz
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 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
Re: [Discussion] documentation framework for OFBiz
On 9 November 2017 at 18:26, Taher Alkhateeb wrote: > Anyway I don't see a reason so far to use pandoc to publish to pdf. > Asciidoctor can publish to html, docbook, pdf and others. Thanks Taher. That's fine by me. Cheers Paul Foxworthy -- Coherent Software Australia Pty Ltd PO Box 2773 Cheltenham Vic 3192 Australia Phone: +61 3 9585 6788 Web: http://www.coherentsoftware.com.au/ Email: i...@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
Hi Paul, First regarding your comment about pandoc, essentially pandoc is a set of readers and writers. Each markup language needs a reader to convert from and a writer to convert to. Asciidoc is missing a reader implementation. I hope someone would implement it eventually. Anyway I don't see a reason so far to use pandoc to publish to pdf. Asciidoctor can publish to html, docbook, pdf and others. I like pandoc, it is a swiss army knife kind of tool for conversion and written in haskell (fantastic). However like a swiss army knife, it is not specialized like a native tool designed for the job. So the time to use pandoc might be if we're stuck or have some limitation with asciidoctor. On Nov 9, 2017 2:28 AM, "Paul Foxworthy" wrote: On 8 November 2017 at 20:33, Taher Alkhateeb wrote: > If you check the link you sent, you will notice that asciidoc is not an > input format in pandoc, but rather an ouput format. > Thanks Taher, My impression was pandoc can read just about any structured input. It's curious AsciiDoc isn't there. So for HTML it's AsciiDoc -- (asciidoctor) --> HTML and for PDF it's AsciiDoc -- (asciidoctor) --> DocBook XML -- (pandoc) --> PDF That sound right? Cheers Paul -- Coherent Software Australia Pty Ltd PO Box 2773 Cheltenham Vic 3192 Australia Phone: +61 3 9585 6788 Web: http://www.coherentsoftware.com.au/ Email: i...@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
On 8 November 2017 at 20:33, Taher Alkhateeb wrote: > If you check the link you sent, you will notice that asciidoc is not an > input format in pandoc, but rather an ouput format. > Thanks Taher, My impression was pandoc can read just about any structured input. It's curious AsciiDoc isn't there. So for HTML it's AsciiDoc -- (asciidoctor) --> HTML and for PDF it's AsciiDoc -- (asciidoctor) --> DocBook XML -- (pandoc) --> PDF That sound right? Cheers Paul -- Coherent Software Australia Pty Ltd PO Box 2773 Cheltenham Vic 3192 Australia Phone: +61 3 9585 6788 Web: http://www.coherentsoftware.com.au/ Email: i...@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
Hi Sharan, As I was explaining to Jacques, there is no tool selection issue. Pandoc cannot handle asciidoc and therefore the best viable choice is asciidoctor. What is stopping us right now is my delay in implementing the feature ( I am about half way through in OFBIZ-9873 to tackle the PoC ). On Nov 8, 2017 1:21 PM, "Sharan Foga" wrote: Hi All At the Open Source Summit in Prague a couple of weeks ago I attended quite a few documentation related talks and also interviewed one of the presenters (Robert Kratky from Red Hat) for FeatherCast. He did a talk about converting legacy docs into more user story based content, so bit like what we need to do. Anyway his recommendation was Asciidoc and he also had some links to resources that could help in our documentation journey. If the tool selection is actually stopping us from moving onto the next step then let's present the proposal options (e.g Asciidoc, Pandoc etc) and ask the community to select their preference.. Thanks Sharan On 08/11/17 10:33, Taher Alkhateeb wrote: > If you check the link you sent, you will notice that asciidoc is not an > input format in pandoc, but rather an ouput format. > > On Nov 8, 2017 12:29 PM, "Jacques Le Roux" > wrote: > > Le 08/11/2017 à 08:25, Paul Foxworthy a écrit : > > On 17 October 2017 at 20:25, Michael Brohl >> wrote: >> >> >> I assume that we can use any Asciidoc editor and need not to use >> >>> Asciidoctor? >>> >>> Hi Michael, >>> >> Asciidoctor is not an editor, it's a text processor that can convert >> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to >> Pandoc >> (https://pandoc.org/). >> >> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown, >> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin >> for IntelliJ IDEA. Your tastes may vary. >> >> Cheers >> >> Paul Foxworthy >> >> Hi Paul, >> > Do you know if there are there good reasons to favor Asciidoctor over > Pandoc? > I'm more in favour of the later because now I know it (thanks to you :)) > and especially because it offers so much possibilities, see graph here > https://pandoc.org/ > You never know what you will need one day... > > Jacques > >
Re: [Discussion] documentation framework for OFBiz
Hi All At the Open Source Summit in Prague a couple of weeks ago I attended quite a few documentation related talks and also interviewed one of the presenters (Robert Kratky from Red Hat) for FeatherCast. He did a talk about converting legacy docs into more user story based content, so bit like what we need to do. Anyway his recommendation was Asciidoc and he also had some links to resources that could help in our documentation journey. If the tool selection is actually stopping us from moving onto the next step then let's present the proposal options (e.g Asciidoc, Pandoc etc) and ask the community to select their preference.. Thanks Sharan On 08/11/17 10:33, Taher Alkhateeb wrote: If you check the link you sent, you will notice that asciidoc is not an input format in pandoc, but rather an ouput format. On Nov 8, 2017 12:29 PM, "Jacques Le Roux" wrote: Le 08/11/2017 à 08:25, Paul Foxworthy a écrit : On 17 October 2017 at 20:25, Michael Brohl wrote: I assume that we can use any Asciidoc editor and need not to use Asciidoctor? Hi Michael, Asciidoctor is not an editor, it's a text processor that can convert AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc (https://pandoc.org/). One of the reasons to choose any wiki-like language (AsciiDoc, Markdown, etc) is you can use any text editor at all. I use a nice AsciiDoc plugin for IntelliJ IDEA. Your tastes may vary. Cheers Paul Foxworthy Hi Paul, Do you know if there are there good reasons to favor Asciidoctor over Pandoc? I'm more in favour of the later because now I know it (thanks to you :)) and especially because it offers so much possibilities, see graph here https://pandoc.org/ You never know what you will need one day... Jacques
Re: [Discussion] documentation framework for OFBiz
Ha thanks Taher, this answer to Michael's question: we indeed need Asciidoctor if we want to transform from Asciidoc to other formats. Then Pandoc can possibly be used for more possibilities Jacques Le 08/11/2017 à 10:33, Taher Alkhateeb a écrit : If you check the link you sent, you will notice that asciidoc is not an input format in pandoc, but rather an ouput format. On Nov 8, 2017 12:29 PM, "Jacques Le Roux" wrote: Le 08/11/2017 à 08:25, Paul Foxworthy a écrit : On 17 October 2017 at 20:25, Michael Brohl wrote: I assume that we can use any Asciidoc editor and need not to use Asciidoctor? Hi Michael, Asciidoctor is not an editor, it's a text processor that can convert AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc (https://pandoc.org/). One of the reasons to choose any wiki-like language (AsciiDoc, Markdown, etc) is you can use any text editor at all. I use a nice AsciiDoc plugin for IntelliJ IDEA. Your tastes may vary. Cheers Paul Foxworthy Hi Paul, Do you know if there are there good reasons to favor Asciidoctor over Pandoc? I'm more in favour of the later because now I know it (thanks to you :)) and especially because it offers so much possibilities, see graph here https://pandoc.org/ You never know what you will need one day... Jacques
Re: [Discussion] documentation framework for OFBiz
If you check the link you sent, you will notice that asciidoc is not an input format in pandoc, but rather an ouput format. On Nov 8, 2017 12:29 PM, "Jacques Le Roux" wrote: Le 08/11/2017 à 08:25, Paul Foxworthy a écrit : > On 17 October 2017 at 20:25, Michael Brohl > wrote: > > > I assume that we can use any Asciidoc editor and need not to use >> Asciidoctor? >> >> Hi Michael, > > Asciidoctor is not an editor, it's a text processor that can convert > AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc > (https://pandoc.org/). > > One of the reasons to choose any wiki-like language (AsciiDoc, Markdown, > etc) is you can use any text editor at all. I use a nice AsciiDoc plugin > for IntelliJ IDEA. Your tastes may vary. > > Cheers > > Paul Foxworthy > > Hi Paul, Do you know if there are there good reasons to favor Asciidoctor over Pandoc? I'm more in favour of the later because now I know it (thanks to you :)) and especially because it offers so much possibilities, see graph here https://pandoc.org/ You never know what you will need one day... Jacques
Re: [Discussion] documentation framework for OFBiz
Le 08/11/2017 à 08:25, Paul Foxworthy a écrit : On 17 October 2017 at 20:25, Michael Brohl wrote: I assume that we can use any Asciidoc editor and need not to use Asciidoctor? Hi Michael, Asciidoctor is not an editor, it's a text processor that can convert AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc (https://pandoc.org/). One of the reasons to choose any wiki-like language (AsciiDoc, Markdown, etc) is you can use any text editor at all. I use a nice AsciiDoc plugin for IntelliJ IDEA. Your tastes may vary. Cheers Paul Foxworthy Hi Paul, Do you know if there are there good reasons to favor Asciidoctor over Pandoc? I'm more in favour of the later because now I know it (thanks to you :)) and especially because it offers so much possibilities, see graph here https://pandoc.org/ You never know what you will need one day... Jacques
Re: [Discussion] documentation framework for OFBiz
On 17 October 2017 at 20:25, Michael Brohl wrote: > I assume that we can use any Asciidoc editor and need not to use > Asciidoctor? > Hi Michael, Asciidoctor is not an editor, it's a text processor that can convert AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc (https://pandoc.org/). One of the reasons to choose any wiki-like language (AsciiDoc, Markdown, etc) is you can use any text editor at all. I use a nice AsciiDoc plugin for IntelliJ IDEA. Your tastes may vary. Cheers Paul Foxworthy -- Coherent Software Australia Pty Ltd PO Box 2773 Cheltenham Vic 3192 Australia Phone: +61 3 9585 6788 Web: http://www.coherentsoftware.com.au/ Email: i...@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
Thank you folks for your feedback. Based on everyone's input, I think perhaps a good way to move forward is by creating a JIRA and making a patch for a PoC. I think altering the OFBiz help system for now might be a bigger task, so for a start, I think I will write some documentation in multiple places and then let gradle consolidate that into an output manual. Then, based on feedback from you we decide on the next step. So I will proceed with creating a JIRA for an initial PoC. Again, thank you for your thoughts, all constructive and valuable. On Wed, Oct 18, 2017 at 11:47 AM, Jacques Le Roux wrote: > Hi Sharan, > > Yes I'm pretty sure we will still need the wiki. For technical points which > don't specially fit in source and also some kind of user documentation, but > the less the better. > > Jacques > > > Le 18/10/2017 à 10:28, Sharan Foga a écrit : >> >> Hi >> >> I would say the first and easier focus is to complete the online help. >> Telling people how to use the screens and applications is a basic >> requirement that we haven't fulfilled for OFBiz yet. Once we have that then >> we can see how it can be expanded to incorporate more general details. I >> think the issue we have had over the years is that OFBiz is so big that it's >> difficult to know where to start. >> >> At least if we can give people information about the application they are >> using, and how to use the screens, then that will give them enough to get >> going. For content we could review the existing help that we have and update >> it into a standard format or template so that it is consistent. >> >> We may also find that we still need the wiki for something so let's see >> what happens >> >> Thanks >> Sharan >> >> On 2017-10-17 13:21, Jacques Le Roux wrote: >>> >>> Yes thanks Taher to have picked this again, >>> >>> I agree with all what have been said so far. >>> >>> You know my preference for asscidoc and asciidoctor. Using the >>> asciidoctor Gradle plugin seems logical to me. >>> >>> I'm all for having all the documentation inside the source. I had even >>> created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423 >>> >>> Questions: >>> >>> 1. Should we continue to provide an online help? Would we reuse/upgrade >>> the current one? >>> 2. Where to put the common documentation? In common or commonext >>> component or in a new documentation folder? Later seems easier for newbies, >>> name >>> says all. >>> 3. I use pandoc to create (from some .md files) md.html files in >>> tools\wiki-files imported in wiki pages. I regularly use a .bat for that. >>> Would we >>> replace also our current .md files? >>> >>> Jacques >>> >>> >>> Le 17/10/2017 à 11:25, Michael Brohl a écrit : >>> Big +1 for this initiative! I have not much to add to Taher's proposal and Sharan's viewpoint. I assume that we can use any Asciidoc editor and need not to use Asciidoctor? I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation would be enough, right? For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to assure a good initial start. I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase. Would be a great starting point for new contributors also. Best regards, Michael Am 17.10.17 um 10:30 schrieb Sharan Foga: > > Hi Taher > > It's great that this conversation has started again. It would be great > to actually start to do something about the integrated help system within > OFBiz itself. We have found limitations with the docbook implementation > we have, so now have a better idea of what we want to achieve. > > In the past we've talked a lot about DITA but to me it seemed a lot > more complex to understand, structure and generally get started. I've > briefly > played about with Ascidoc and it seems pretty simple enough to get the > hang of and that to me is an important thing. I also like the idea of > being > able to render multiple formats (and it would be good to make them look > nicer and easier to read). > > Getting a good and functioning help framework into our codebase is long > overdue and I'm sure will add some great benefits and also encourage > documentation contributions from our community. > > Big +1 from me! > > Thanks > Sharan > > > On 17/10/17 10:01, Taher Alkhateeb wrote: >> >> Hello Folks, >> >> We've had this discussion multiple
Re: [Discussion] documentation framework for OFBiz
Hi Sharan, Yes I'm pretty sure we will still need the wiki. For technical points which don't specially fit in source and also some kind of user documentation, but the less the better. Jacques Le 18/10/2017 à 10:28, Sharan Foga a écrit : Hi I would say the first and easier focus is to complete the online help. Telling people how to use the screens and applications is a basic requirement that we haven't fulfilled for OFBiz yet. Once we have that then we can see how it can be expanded to incorporate more general details. I think the issue we have had over the years is that OFBiz is so big that it's difficult to know where to start. At least if we can give people information about the application they are using, and how to use the screens, then that will give them enough to get going. For content we could review the existing help that we have and update it into a standard format or template so that it is consistent. We may also find that we still need the wiki for something so let's see what happens Thanks Sharan On 2017-10-17 13:21, Jacques Le Roux wrote: Yes thanks Taher to have picked this again, I agree with all what have been said so far. You know my preference for asscidoc and asciidoctor. Using the asciidoctor Gradle plugin seems logical to me. I'm all for having all the documentation inside the source. I had even created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423 Questions: 1. Should we continue to provide an online help? Would we reuse/upgrade the current one? 2. Where to put the common documentation? In common or commonext component or in a new documentation folder? Later seems easier for newbies, name says all. 3. I use pandoc to create (from some .md files) md.html files in tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would we replace also our current .md files? Jacques Le 17/10/2017 à 11:25, Michael Brohl a écrit : Big +1 for this initiative! I have not much to add to Taher's proposal and Sharan's viewpoint. I assume that we can use any Asciidoc editor and need not to use Asciidoctor? I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation would be enough, right? For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to assure a good initial start. I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase. Would be a great starting point for new contributors also. Best regards, Michael Am 17.10.17 um 10:30 schrieb Sharan Foga: Hi Taher It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve. In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being able to render multiple formats (and it would be good to make them look nicer and easier to read). Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage documentation contributions from our community. Big +1 from me! Thanks Sharan On 17/10/17 10:01, Taher Alkhateeb 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
Re: [Discussion] documentation framework for OFBiz
Hi I would say the first and easier focus is to complete the online help. Telling people how to use the screens and applications is a basic requirement that we haven't fulfilled for OFBiz yet. Once we have that then we can see how it can be expanded to incorporate more general details. I think the issue we have had over the years is that OFBiz is so big that it's difficult to know where to start. At least if we can give people information about the application they are using, and how to use the screens, then that will give them enough to get going. For content we could review the existing help that we have and update it into a standard format or template so that it is consistent. We may also find that we still need the wiki for something so let's see what happens Thanks Sharan On 2017-10-17 13:21, Jacques Le Roux wrote: > Yes thanks Taher to have picked this again, > > I agree with all what have been said so far. > > You know my preference for asscidoc and asciidoctor. Using the asciidoctor > Gradle plugin seems logical to me. > > I'm all for having all the documentation inside the source. I had even > created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423 > > Questions: > > 1. Should we continue to provide an online help? Would we reuse/upgrade the > current one? > 2. Where to put the common documentation? In common or commonext component > or in a new documentation folder? Later seems easier for newbies, name > says all. > 3. I use pandoc to create (from some .md files) md.html files in > tools\wiki-files imported in wiki pages. I regularly use a .bat for that. > Would we > replace also our current .md files? > > Jacques > > > Le 17/10/2017 à 11:25, Michael Brohl a écrit : > > Big +1 for this initiative! > > > > I have not much to add to Taher's proposal and Sharan's viewpoint. > > > > I assume that we can use any Asciidoc editor and need not to use > > Asciidoctor? > > > > I think we have to decide what we will do with our Wiki based documentation > > then. If we have up-to-date documentation in the components and can > > generate up-to-date documentation every night, pretty much of the Wiki > > documentation would be obsolete. A simple link to the generated > > documentation > > would be enough, right? > > > > For new code in framework and plugins, I would strongly recommend to have > > mandatory documentation as part of the first commit to the codebase to > > assure a good initial start. > > > > I think we should just start with a proof-of-concept by moving some small > > part of the documentation to Asciidoc and into the codebase. > > > > Would be a great starting point for new contributors also. > > > > Best regards, > > > > Michael > > > > > > Am 17.10.17 um 10:30 schrieb Sharan Foga: > >> Hi Taher > >> > >> It's great that this conversation has started again. It would be great to > >> actually start to do something about the integrated help system within > >> OFBiz itself. We have found limitations with the docbook implementation we > >> have, so now have a better idea of what we want to achieve. > >> > >> In the past we've talked a lot about DITA but to me it seemed a lot more > >> complex to understand, structure and generally get started. I've briefly > >> played about with Ascidoc and it seems pretty simple enough to get the > >> hang of and that to me is an important thing. I also like the idea of > >> being > >> able to render multiple formats (and it would be good to make them look > >> nicer and easier to read). > >> > >> Getting a good and functioning help framework into our codebase is long > >> overdue and I'm sure will add some great benefits and also encourage > >> documentation contributions from our community. > >> > >> Big +1 from me! > >> > >> Thanks > >> Sharan > >> > >> > >> On 17/10/17 10:01, Taher Alkhateeb 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 documentat
Re: [Discussion] documentation framework for OFBiz
Yes thanks Taher to have picked this again, I agree with all what have been said so far. You know my preference for asscidoc and asciidoctor. Using the asciidoctor Gradle plugin seems logical to me. I'm all for having all the documentation inside the source. I had even created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423 Questions: 1. Should we continue to provide an online help? Would we reuse/upgrade the current one? 2. Where to put the common documentation? In common or commonext component or in a new documentation folder? Later seems easier for newbies, name says all. 3. I use pandoc to create (from some .md files) md.html files in tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would we replace also our current .md files? Jacques Le 17/10/2017 à 11:25, Michael Brohl a écrit : Big +1 for this initiative! I have not much to add to Taher's proposal and Sharan's viewpoint. I assume that we can use any Asciidoc editor and need not to use Asciidoctor? I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation would be enough, right? For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to assure a good initial start. I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase. Would be a great starting point for new contributors also. Best regards, Michael Am 17.10.17 um 10:30 schrieb Sharan Foga: Hi Taher It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve. In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being able to render multiple formats (and it would be good to make them look nicer and easier to read). Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage documentation contributions from our community. Big +1 from me! Thanks Sharan On 17/10/17 10:01, Taher Alkhateeb 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
Re: [Discussion] documentation framework for OFBiz
Big +1 for this initiative! I have not much to add to Taher's proposal and Sharan's viewpoint. I assume that we can use any Asciidoc editor and need not to use Asciidoctor? I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation would be enough, right? For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to assure a good initial start. I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase. Would be a great starting point for new contributors also. Best regards, Michael Am 17.10.17 um 10:30 schrieb Sharan Foga: Hi Taher It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve. In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being able to render multiple formats (and it would be good to make them look nicer and easier to read). Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage documentation contributions from our community. Big +1 from me! Thanks Sharan On 17/10/17 10:01, Taher Alkhateeb 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 smime.p7s Description: S/MIME Cryptographic Signature
Re: [Discussion] documentation framework for OFBiz
Hi Taher It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve. In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being able to render multiple formats (and it would be good to make them look nicer and easier to read). Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage documentation contributions from our community. Big +1 from me! Thanks Sharan On 17/10/17 10:01, Taher Alkhateeb 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
[Discussion] documentation framework for OFBiz
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
