On 2018/03/13 16:37:31, Taher Alkhateeb <slidingfilame...@gmail.com> 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 <sha...@apache.org> 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 <slidingfilame...@gmail.com> 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 > >> <michael.br...@ecomify.de> 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 <sha...@apache.org> > >> >>>> 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 <slidingfilame...@gmail.com> > >> >>>>> 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" <michael.br...@ecomify.de> > >> >>>>>> 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 > >> >>>>>> <michael.br...@ecomify.de> > >> >>>>>> 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 > >> >>>>>>> > >> >>>>>>> > >> >> > >> >> > >> > > >> > > >> >
