[Discussion] documentation framework for OFBiz
Locked
1234
1234
Re: [Discussion] documentation framework for OFBiz
 
|
Re: [Discussion] documentation framework for OFBiz
|
|
In reply to this post by taher
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 <[hidden email]> 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 <[hidden email]> 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" <[hidden email]> 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 <[hidden email]> 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 (5K)
Re: [Discussion] documentation framework for OFBiz
|
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 <[hidden email]> 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 <[hidden email]> 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" <[hidden email]> 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 <[hidden email]> 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
|
|
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 <[hidden email]> 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 >>>> <[hidden email]> 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" >>>>> <[hidden email]> 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 >>>>> <[hidden email]> 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
|
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> >>>>>> 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" <[hidden email]> >>>>>>> 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 <[hidden email]> >>>>>>> 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
|
|
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 <[hidden email]> 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 <[hidden email]> >>> 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 <[hidden email]> >>>>>>> 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 <[hidden email]> >>>>>>>> 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" <[hidden email]> >>>>>>>>> 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 >>>>>>>>> <[hidden email]> >>>>>>>>> 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
|
|
In reply to this post by Michael Brohl-3
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 <[hidden email]> 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 >>>> <[hidden email]> 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" >>>>> <[hidden email]> 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 >>>>> <[hidden email]> 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
|
|
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 > <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> >>>>>> 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" <[hidden email]> >>>>>>> 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 <[hidden email]> >>>>>>> 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
|
|
Listing All Menu Items
|
|
Re: Listing All Menu Items
|
|
Re: Listing All Menu Items
|
|
Re: Listing All Menu Items
|
Re: Listing All Menu Items
|
|
Re: Listing All Menu Items
|
|
Re: Listing All Menu Items
|
|
| Free forum by Nabble | Edit this page |