Can I include Java constant value in AsciiDoctor document?

Question

For example, lets have a Java constant in some class

public class MyClass{
  public static final String ENDPOINT="http://example.com"
}

and lets try to describe that class in AsciiDoctor (corporate docs reasons)

==== My class

..... some descripton ..... 
It is exposed trough http://example.com

Now every time I change the endpoint, I have to update docs manually as well (IDE find-and-replace will do the trick obviously). Is there a way to include Java constant into the AsciiDoc so I don't have to copy its value into the docs?

I would gladly see something like {import my.package.MyClass#ENDPOINT} or something similiar.

You can use attributes in Asciidoc, then you only have to define the constant once for your documentation (e.g. in the header of the doc, or as a parameter when building the docs. You could also generate the Asciidoc from Java code, and then use the constant, but that seems a bit exotic to me. Alternatively, you could define the constant in your build, and then have your build generate the source code with the necessary constant, and build your documentation using that value. — Mark Rotteveel, Oct 27 '21 at 07:17
But is there a syntax to include such contant like `whole.package.MyClass#myConstant`? Docs are built in the pipeline in java anyway in my case so I can easily include system as a dependency. The only thing is, how to refer to it? — Antoniossss, Oct 27 '21 at 07:21
Or maybe I can write my own preprocessor of some kind to do just that? — Antoniossss, Oct 27 '21 at 07:23
AsciiDoctor is Ruby or JavaScript based (AsciiDoctor J is wrapper around JRuby), so it's unlikely, and if there were it would probably be explicitly spelled out in the documentation. — Mark Rotteveel, Oct 27 '21 at 07:23
That said, AsciiDoctor (and Asciidoctor J) has several extension points, so maybe you could write something custom to do it, but personally I would rather drive it from my build system populating both my Java code and AsciiDoctor attributes then adding something to AsciiDoctor to parse Java code. — Mark Rotteveel, Oct 27 '21 at 07:25
There is https://blog.mrhaki.com/2014/04/awesome-asciidoc-include-partial-parts.html but that is line based, you can't do part of a line. — Wim Deblauwe, Nov 08 '21 at 15:54

score 1 · Answer 1 · answered Dec 07 '21 at 09:05

One other solution is to use the include-pattern of asciidoctor which is described here. https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/

In short.

Define a tagged region:

public class MyClass{
  //tag::endpointdefinition[]
  public static final String ENDPOINT="http://example.com"
  //end::endpointdefinition[]
}

include it your document

[source,java]
----
include::pathYourFile.java[tag=endpointdefinition] 
----

To optimize it a little bit you could break your lines different int the java file and place the tag definition on that. You could also remove the source around including the java file.

score 0 · Answer 2 · edited Dec 15 '21 at 18:15

I'd write a shell script (PERL, whatever) that greps your Java code for a regex something like 'class (\w+).*ENDPOINT="([^"]+)', sending the results to an include file (./endpoints.adoc) using ':\1_endpoint: \2', thus:

:MyClass_endpoint: http://example.com
:MyOtherClass_endpoint: http://other.example.com

Then, at the top of your AsciiDoc file insert: include::endpoints.adoc[]

and then refer to {MyClass_endpoint} and {MyOtherClass_endpoint} in the body.

Then, simply run the script as part of your toolchain prior to calling AsciiDoctor.

Can I include Java constant value in AsciiDoctor document?

2 Answers2

Linked