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

[Nicolas Malin (Jira)]

     [ https://issues.apache.org/jira/browse/OFBIZ-9873?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Jacques Le Roux reopened OFBIZ-9873:
------------------------------------

Hi Taher,

I just tried to use generateOfbizDocumentation but got an issue with rouge which seems specific to Windows

{code}
C:\projectsASF\ofbiz>gradlew generateOfbizDocumentation
:deleteOfbizDocumentation
:generateOfbizDocumentation
(RuntimeError) asciidoctor: FAILED: required gem 'rouge' is not installed. Processing aborted.
:generateOfbizDocumentation FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':generateOfbizDocumentation'.
> Error running Asciidoctor

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

BUILD FAILED

Total time: 15.599 secs
{code}

I then tried to install rouge (using last https://rubyinstaller.org/downloads/ : ruby+Devkit 2.4.4-1 (x64) )

{code}
C:\projectsASF\ofbiz>gem install rouge
Successfully installed rouge-3.1.1
Parsing documentation for rouge-3.1.1
Done installing documentation for rouge after 3 seconds
1 gem installed
{code}

But still got an issue

{code}
C:\projectsASF\ofbiz>gradlew generateOfbizDocumentation
Parallel execution is an incubating feature.
:deleteOfbizDocumentation
:generateOfbizDocumentation
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Text
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Error
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Other
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Keyword
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Name
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Literal
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Operator
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Punctuation
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Comment
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:71: warning: already initialized constant Generic
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:178: warning: already initialized constant Num
uri:classloader:/gems/rouge-2.0.7/lib/rouge/token.rb:179: warning: already initialized constant Str
uri:classloader:/gems/rouge-2.0.7/lib/rouge/guessers/modeline.rb:5: warning: already initialized constant EMACS_MODELINE
uri:classloader:/gems/rouge-2.0.7/lib/rouge/guessers/modeline.rb:10: warning: already initialized constant VIM_MODELINE_1
uri:classloader:/gems/rouge-2.0.7/lib/rouge/guessers/modeline.rb:15: warning: already initialized constant VIM_MODELINE_2
uri:classloader:/gems/rouge-2.0.7/lib/rouge/guessers/modeline.rb:17: warning: already initialized constant MODELINES
uri:classloader:/gems/rouge-2.0.7/lib/rouge/regex_lexer.rb:279: warning: already initialized constant MAX_NULL_SCANS
uri:classloader:/gems/rouge-2.0.7/lib/rouge/lexers/bsl.rb:11: warning: already initialized constant KEYWORDS
uri:classloader:/gems/rouge-2.0.7/lib/rouge/lexers/bsl.rb:29: warning: already initialized constant BUILTINS
(RuntimeError) asciidoctor: FAILED: required gem 'rouge' is not installed. Processing aborted.
:generateOfbizDocumentation FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':generateOfbizDocumentation'.
> Error running Asciidoctor

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.
{code}

I looked for fix, but gave up:
https://github.com/junit-team/junit5/issues/799
https://github.com/jneen/rouge/issues/661
https://github.com/junit-team/junit5/issues/777
https://github.com/junit-team/junit5/issues/770

Of course, it works when I remove
{{:source-highlighter: rouge}}
Do you have an idea for a better solution (apart using coderay)

> 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
>             Fix For: Upcoming Branch
>
>         Attachments: OFBIZ-9873.patch, 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
(v7.6.3#76005)