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 <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
smime.p7s
Description: S/MIME Cryptographic Signature
