[jira] [Updated] (ISIS-2524) Tooling: Ideas to enhance 'projdoc' support

["Daniel Keir Haywood (Jira)" <ji...@apache.org>]

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

Daniel Keir Haywood updated ISIS-2524:
--------------------------------------
    Fix Version/s:     (was: 2.0.0-M6)
                   2.0.0-M7

> Tooling: Ideas to enhance 'projdoc' support
> -------------------------------------------
>
>                 Key: ISIS-2524
>                 URL: https://issues.apache.org/jira/browse/ISIS-2524
>             Project: Isis
>          Issue Type: Improvement
>    Affects Versions: 2.0.0-M5
>            Reporter: Daniel Keir Haywood
>            Priority: Major
>             Fix For: 2.0.0-M7
>
>
> in adopting the 'projdoc' global index, I've commented out some existing material.  It'd be nice to have that material in the source code and projdoc generate pages the way I'd like them.
> Several ideas:
> *Auto-detect examples*
> As per the ISIS-2524 branch that sketches this out, automatically detect (from src/test/java) any Xxx_example.java classes and copy over to examples/, post-process and include using include::example$Xxx_example.adoc[]
> *Xrefs to page anchors*
> for example, in javadoc this: \{@link ActionLayout#cssClassFa}   should correspond to this: xref:Actionlayout#cssClassfa[].
> *Implementations section*
> **(This is demo'd in the origin/ISIS-2524 branch)... automatically generate an "implementations" section, identifying the domain service and also providing example code indicating the module to @Import and the pom to reference in <dependencies> of the pom.xml
> *Copy to clipboard***
> The default antora template now has a widget to copy text to clipboard (see [https://gitlab.com/antora/antora-ui-default/-/issues/70)]  ... it would be nice to have the same.
> *Asciidoclet*
> to allow richer text, to allow comments to be written in Asciidoc.  This would leverage the existing asciidoclet doclet in our CI ([https://github.com/asciidoctor/asciidoclet#example),] while users of IntelliJ could also benefit from asciidoclet plugin support ([https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoclet.html).|https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoclet.html)]
> If that is unwieldy, then perhaps simply allow .adoc comments to be stored alongside the .java files (similar to our layout files) and have projdoc stitch it all together.
> For example, the extended material for @Action#semanticsOf element would reside in Action#semanticsOf.adoc, right alongside Action.java.
>  



--
This message was sent by Atlassian Jira
(v8.3.4#803005)