fixup Asciidoclet using include paths

[ahus1]

Hi @chrisvest, I was looking for some real-world Asciidoclet examples and came across your project.

While implementing Asciidoclet support for IntelliJ (https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues/103) I found some include paths that should start at the root of the project (at least that's how I read the Asciidoclet documentation). Strangely enough this didn't affect the Javadoc generation.

Now the include paths are consistent. I generated the docs locally and they worked before and after.

This PR also fixed the indentation of included source snippets.

I wasn't sure if the PR should go into 3.1 or 3.2. If I should provide a PR for 3.1 as well please let me know.

If you happen to be a user of IntelliJ and the AsciiDoc plugin for IntelliJ I'm happy for feedback regarding Asciidoclet support via GitHub issues.

[codecov[bot]]

Codecov Report

Merging #141 into 3.2 will decrease coverage by 0.19%. The diff coverage is n/a.

@@             Coverage Diff              @@
##                3.2     #141      +/-   ##
============================================
- Coverage     95.98%   95.79%   -0.20%     
+ Complexity      391      388       -3     
============================================
  Files            35       35              
  Lines          1047     1047              
  Branches        117      117              
============================================
- Hits           1005     1003       -2     
  Misses           25       25              
- Partials         17       19       +2     

Impacted Files	Coverage Δ	Complexity Δ
src/main/java/stormpot/Pool.java	92.30% <ø> (ø)	6.00 <0.00> (ø)
src/main/java/stormpot/PoolTap.java	100.00% <ø> (ø)	5.00 <0.00> (ø)
src/main/java/stormpot/BAllocThread.java	98.49% <0.00%> (-1.01%)	74.00% <0.00%> (-3.00%)

[chrisvest]

Hi @ahus1!

Yes, 3.2 is the correct branch to work on. The changes look good, thanks! I just want to try them locally myself before merging, and I just changed jobs and have a lot of stuff going on because of that, so please be patient about that.

I use the Intellij asciidoctor plugin for writing all the documentation here. I was also using it when writing docs for Neo4j. It's great stuff.

The asciidoclet support you're working on, does it work even though I'm using my own fork of asciidoclet in this repo? Someone else did a fork based on my fork which also upgrades asciidoctor to 2.x, and enables asciidoctor-diagrams. I'd like to eventually do that in my own fork as well, but haven't had a personally motivating use case to prioritise it yet.

[ahus1]

Hi @chrisvest - the IntelliJ plugin works independent of the Asciidoclet Javadoc plugin: it takes the AsciiDoc source from the Javadoc and passes it to an 2.x AsciidoctorJ instance.

Therefore the results of a "reals" Asciidoclet and the preview in the editor might differ. You could see them as independent implementations. Once user report diversions via GitHub issues or pull requests, we'll work towards closing the gap. The implementation will mature over time.

Diagrams are currently not working. Feel free to provide a test case and a GitHub issue.

Talking about forks: I hope Asciidoclet will provide future releases and include changes in other forks; this way the IntelliJ plugin would need to track only one target.

[chrisvest]

I have not forgotten about this. I am just caught up in unforeseen circumstances that means it'll be months before I can touch even something as simple as this… 😕

[ahus1]

No worries, take your time.

Just a note: Asciidoclet support moved to its own companion plugin for IntelliJ 2020.2+.