You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ofbiz.apache.org by "Taher Alkhateeb (JIRA)" <ji...@apache.org> on 2018/01/12 16:51:00 UTC

[jira] [Comment Edited] (OFBIZ-9873) Create a PoC for a documentation system for OFBiz based on Asciidoc

    [ https://issues.apache.org/jira/browse/OFBIZ-9873?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16324200#comment-16324200 ] 

Taher Alkhateeb edited comment on OFBIZ-9873 at 1/12/18 4:50 PM:
-----------------------------------------------------------------

Added a with a very simple implementation to discuss on the community ML.

To test this patch do the following:
- apply the patch
- temporarily rename themes/common to something else (too long to explain now)
- pick any component you like, and inside it create the directory src/docs/asciidoc
- Inside this new directory create a file that ends with adoc extension (e.g. test.adoc)
- run the task ./gradlew publishDocumentation
- Observe in build/docs/asciidoc/${component-name}/html5/test.html


was (Author: taher):
Added a with a very simple implementation to discuss on the community ML.

To test this patch do the following:
- apply the patch
- temporarily rename themes/common to something else (too long to explain now)
- pick any component you like, and inside it create the directory src/docs/asciidoc
- Inside this new directory create a file that ends with adoc extension (e.g. test.adoc)
- run the task ./gradlew publishDocumentation
- Observe in build/docs/${component-name}/html5/test.html

> Create a PoC for a documentation system for OFBiz based on Asciidoc
> -------------------------------------------------------------------
>
>                 Key: OFBIZ-9873
>                 URL: https://issues.apache.org/jira/browse/OFBIZ-9873
>             Project: OFBiz
>          Issue Type: Improvement
>    Affects Versions: Upcoming Branch
>            Reporter: Taher Alkhateeb
>            Assignee: Taher Alkhateeb
>            Priority: Minor
>         Attachments: OFBIZ-9873.patch
>
>
> In reference to the [discussion thread|https://lists.apache.org/thread.html/8cc03b7b8733512244129ddae9e0cc1fb2a28e3e250aba1c8cf678f8@%3Cdev.ofbiz.apache.org%3E] this is an attempt to create a PoC for OFBiz documentation system based on Asciidoc. The main assumptions for the design of this system are:
> - 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.



--
This message was sent by Atlassian JIRA
(v6.4.14#64029)