I'm seeing this warning in my Gradle-based project:

WARN: tilt autoloading 'tilt/haml' in a non thread-safe way; explicit require 'tilt/haml' suggested.

The same warning also shows up in this sample project: https://github.com/JGrenier/asciidoclet-sample

I'm using Gradle 2.6.

It would be nice to see the JavaDoc for this project published. As I mentioned in a comment on another issue, I'm looking for examples of Asciidoclet being used in real-world projects. I decided to see if there was any dog-food eating going on -- and there was! -- but it would be nice to see the rendered HTML published somewhere.

When building with an upgraded version of asciidoctorj, log messages are issued noting that it is ignoring a given library and to try to run a gem command:

john@john-desktop:~/dev/asciidoclet-sample$ ./gradlew clean build javadoc
:project:clean
:project:compileJava
:project:processResources UP-TO-DATE
:project:classes
:project:jar
:project:assemble
:project:compileTestJava UP-TO-DATE
:project:processTestResources UP-TO-DATE
:project:testClasses UP-TO-DATE
:project:test UP-TO-DATE
:project:check UP-TO-DATE
:project:build
:project:jrubyPrepareGems
Successfully installed asciidoctor-diagram-1.3.1
Successfully installed asciidoctor-1.5.3
2 gems installed
:project:javadoc
Ignoring bigdecimal-1.2.7 because its extensions are not built.  Try: gem pristine bigdecimal --version 1.2.7
Ignoring executable-hooks-1.3.2 because its extensions are not built.  Try: gem pristine executable-hooks --version 1.3.2
Ignoring ffi-1.9.10 because its extensions are not built.  Try: gem pristine ffi --version 1.9.10
Ignoring gem-wrappers-1.2.7 because its extensions are not built.  Try: gem pristine gem-wrappers --version 1.2.7
Ignoring io-console-0.4.5 because its extensions are not built.  Try: gem pristine io-console --version 0.4.5
Ignoring json-1.8.3 because its extensions are not built.  Try: gem pristine json --version 1.8.3
Ignoring psych-2.0.17 because its extensions are not built.  Try: gem pristine psych --version 2.0.17
Ignoring psych-2.0.15 because its extensions are not built.  Try: gem pristine psych --version 2.0.15
Ignoring rjb-1.5.4 because its extensions are not built.  Try: gem pristine rjb --version 1.5.4
Ignoring rjb-1.5.3 because its extensions are not built.  Try: gem pristine rjb --version 1.5.3
Ignoring rjb-1.4.9 because its extensions are not built.  Try: gem pristine rjb --version 1.4.9
WARN: tilt autoloading 'tilt/haml' in a non thread-safe way; explicit require 'tilt/haml' suggested.

@mojavelinux or @robertpanzer any thoughts on this one?

It looks like Guava, JRuby, and AsciidoctorJ are bundled in the jar. Is it possible to have a -core version without them, like asciidoctor-ant has done?

In Hibernate we are trying to migrate to using Asciidoclet to author Javadoc. However, as Hibernate is a huge project it is simply not feasible to convert all of the docs at once so we have been working on a phased approach change pieces at a time such that we end up with a mix of traditional and Asciidoclet javadoc markup within the same project.

But in practice this has led to problems rendering the javadocs. If we enable Asciidoclet it messes up some of the traditional Javadoc markup; e.g. it escapes and "passes through" all HTML tags (you literally end up with <p/>, <li>, etc in the rendered HTML output). And if we disable Asciidoclet, of course the standard doclet butchers the Asciidoctor markup.

Are we missing something here? Does a project have to use one or the other approach? If so, that is severely limiting for larger projects to move to Asciidoclet

hi,
Is there a way to have accentuated caracters rendered correctly ?

see this project sample i made to reproduce the problem.

é is rendered as é

https://github.com/JGrenier/asciidoclet-sample.git

I succeeded in using asciidoctor diagram working in a pure java project but it requires some prerequisites to get it working.
May be these explainations should be added to the asciidoclet documentation.

See my simple sample for a working example.
May be i haven't configured my project in the right way, so do not hesitate to tell me if i am wrong.

The missing information is :

dependencies {
//add the jruby plugin to install the gem
classpath 'com.github.jruby-gradle:jruby-gradle-plugin:0.1.11'
}
apply plugin: 'com.github.jruby-gradle.base'

dependencies {
asciidoclet 'org.asciidoctor:asciidoclet:1.+'
gems 'rubygems:asciidoctor-diagram:1.+'
}

javadoc {
dependsOn jrubyPrepareGems
options.docletpath = configurations.asciidoclet.files.asType(List)
options.doclet = 'org.asciidoctor.Asciidoclet'
options.overview = "src/main/java/overview.adoc"
options.addStringOption "-base-dir", "${projectDir}"
options.addStringOption "-attributes-file", "${projectDir}/config/javadoc-attributes.adoc"
options.addStringOption "-require", "asciidoctor-diagram"
options.addStringOption "-gem-path", "${jrubyPrepareGems.outputDir}"
options.addStringOption "-attribute", "data-uri," +
"name=${project.name}," +
"version=${project.version}," +
"title-link=http://example.com[${project.name} ${project.version}]"
}

Thanks in advance.

JavaDoc can be written for type parameters such as <R> in the following example:

/**
 * JSON-RPC remote method call that returns 'response.result`
 *
 * @param method JSON RPC method call to send
 * @param params JSON RPC params
 * @param <R> Type of result object
 * @return the 'response.result' field of the JSON RPC response converted to type R
 */
protected <R> R send(String method, List<Object> params, Class<R> resultType) throws IOException, JsonRPCStatusException {

When processing with Asciidoclet I get the following error:

RPCClient.java:144: warning - @param argument "<R>" is not a parameter name

It looks like Asciidoclet is escaping the pointy brackets before passing them through to JavaDoc. If I remove the pointy brackets, JavaDoc doesn't recognize R as a parameter.

Publish to jcenter on Bintray. The goal is to get all Asciidoctor artifacts into jcenter, which provides a nice dashboard and repository for binary artifacts.

See AsciidoctorJ and the Asciidoctor Gradle plugin for examples on how to setup. It's pretty straightforward. I recommend that we follow the same approach of publishing to bintray under your own username, then clicking "Link to jcenter" to make it available in jcenter.

The latest version available in maven central is 1.5.4, see http://repo1.maven.org/maven2/org/asciidoctor/asciidoclet/

I can see 1.5.6 available on bintray.

When generating javadoc using Java 9, the following warning is displayed:

javadoc: warning - Unrecognized Java version 9, using Java 7/8 stylesheet

This can be fixed by creating new RegEx patterns in Stylesheets.java and creating new stylesheets for Java 9 and later. It looks like new stylesheets are required because of Issue #72 (and possibly other issues.)

As it stands, asciidoctor's rendered output relies on css for styling elements. Including this in the generated asciidoclet source will bring the generated output closer to what is intended with Asciidoctor's output.

Should we also include the ability to add additional css?

Suggestion: remove some of the ifdef's - as the readme.adoc will probably only be rendered on Github...

I'm trying to upgrade my bitcoinj-addons repository to Gradle 3.1-rc-1 and when I try to run Gradle (even a gradle clean) I get the following error message:

Cannot change strategy of configuration ':asciidoclet' after it has been resolved.

This is true as of ConsensusJ/consensusj@e22470e

Am I doing something wrong? Has anyone used asciidoclet with Gradle 3.x yet?

p.s. the "Composite Builds" feature of Gradle 3.1 is really awesome -- people with library projects are going to want to upgrade to it quickly, I think.

I am using asciidoctorj 1.5.4, asciidoctorj-pdf 1.5.0-alpha.11 and asciidoclet 1.5.4 in a maven project. I have defined some custom BlockProcessors and registered them using the javaExtensionRegistry and created the proper files in my META-INF/services folder.

Generating the PDF works flawlessly, and my custom BlockProcessors are recognized and rendered as they should be. In the Javadoc however, the custom BlockProcessors are not rendered at all, and asciidoctor reports the many warnings about the BlockProcessors not being recognized:

asciidoctor: WARNING: <stdin>: line 7: invalid style for paragraph: eks

If I throw a RuntimeException in the register method of my class that implements ExtensionRegistry, I can see that generating a PDF will throw the exception, but generating the Javadoc does not. It would seem that that extensions are not being loaded by AsciidoctorJ when generating the Javadoc.

Here is one of my BlockProcessors:

public class EksBlock extends BlockProcessor {

  public EksBlock(String name, Map<String, Object> config) {
    super(name, config);
  }

  @Override
  public Object process(AbstractBlock parent, Reader reader, Map<String, Object> attributes) {
    // attributes that a normal admonition would accept
    attributes.put("name", "EKS");
    attributes.put("caption", "EKS.");

    // just pass along the text
    String admonitionText = reader.read();

    return createBlock(parent, "admonition", admonitionText, attributes, new HashMap<Object, Object>());
  }
}

My ExtensionRegistry implementation:

public class BlockExtensionRegistry implements ExtensionRegistry {

  public void register(Asciidoctor asciidoctor) {
    Map<String, Object> config = new HashMap<String, Object>();
    config.put("contexts", Arrays.asList(":paragraph"));
    config.put("content_model", ":compound");

    EksBlock eksBlock = new EksBlock("eks", config);
  }
}

I also have the following file:

src/main/resources/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry

File content:

com.example.extension.asciidoctor.BlockExtensionRegistry

Snippet from pom.xml

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-javadoc-plugin</artifactId>
	<configuration>
	  <failOnError>false</failOnError>
	  <noqualifier>all</noqualifier>
	  <show>private</show>
	  <doclet>org.asciidoctor.Asciidoclet</doclet>
	  <docletArtifact>
		<groupId>org.asciidoctor</groupId>
		<artifactId>asciidoclet</artifactId>
		<version>1.5.4</version>
	  </docletArtifact>
	  <additionalparam>
		--base-dir ${project.basedir}
		--attribute "name=${project.name}"
		--attribute "version=${project.version}"
		--attribute
		"templateDir=${project.basedir}/src/docs/asciidoc/template"
	  </additionalparam>
	</configuration>
</plugin>

Am I missing some configuration in my pom.xml that will allow Asciidoclet to register the extensions, or is this an issue with Asciidoclet?

So now that we have preliminary support for running under Java 9+, it would be nice to make a SNAPSHOT release.

Is there documentation on how this is done? Who as been doing this? What should we do?

have forked this doclet to https://github.com/jnorthr/asciidoclet and started to build a gradle wrapper around it. This is just so i can do some testing in isolation. If you care to try, you can clone my repo into some directory on your system, then CD into that directory and from a terminal command line do :

gradlew

that's all ya need as gradle carries it's own jars for self-execution as a 'wrapper' so gradlew just runs the internal gradle. It looks at the build.gradle script to get a default list of tasks to do(clean,build...) and also sees all those code dependencies the doclet needs to do it's thing and downloads them into it's own cache. I have made a guess at which dependencies to use and this combination seem to work:

asciidoclet 'org.asciidoctor:asciidoclet:0.1.3'  
compile group:'org.asciidoctor', name:'asciidoctor-java-integration', version:'0.1.4'
compile 'org.powermock:powermock-api-mockito:1.4.12'
compile 'org.codehaus.groovy:groovy:2.2.1'
compile group: 'junit',name:'junit',version: '4.+' 
compile group: 'org.powermock', name:'powermock-module-junit4', version:'1.5.4'
testCompile group: 'junit',name:'junit',version: '4.+' 

may not be the right combo but it all runs fine ! see screenshots to follow:

while the command to create javadocs looks like this:

there's some warnings there we need to figure out. any ideas guys ??

next up is more heavy-duty testing - more soon ;-}

Asciidoctor supports extensions. It would be fantastic to be able to leverage extensions in asciidoclet.

Concretely, I'm thinking about the https://github.com/asciidoctor/asciidoctor-diagram extension. Supporting this extension would allow us to generate uml in javadoc code, like the following:

http://asciidoctor.org/news/2014/02/18/plain-text-diagrams-in-asciidoctor/

This would be yet another game changer.

When I try to run the current Asciidoclet 1.5.5-SNAPSHOT with Java 10 via the Gradle javadoc task I get the following error:

javadoc: error - invalid flag: -d

This is because the old "Standard Doclet" was removed in Java 10 (http://www.oracle.com/technetwork/java/javase/10-relnote-issues-4108729.html#JDK-8177511) and Asciidoclet runs as a preprocessor that in-turn calls the Standard Doclet.

I'm not sure if this is worth trying to fix separately from Issue #71. In other words there are two approaches to resolving this:

1. Create an Asciidoclet that implements the new JavaDoc API and have this new Asciidoclet call the new standard doclet for generating HTML. i.e. Issue #71
2. Update the current Asciidoclet to use the new Standard Doclet w/o Asciidoclet itself implementing the new JavaDoc API. (I don't even know if this is possible)

So, it seems to me like #71 is probably the best solution. But there may be other solutions and we need to track this specific issue that we are seeing under Java 10+.

There is a high-degree of duplication in the Asciidoclet documentation spread over three places:

• The Github project README.adoc
• The 1.5.0 Release Notes
• The Asciidoclet Guide on Asciidoctor.org

The source code for these docs should be consolidated for ease-of-maintenance and it should probably be published to a single place as well.

My recommendation is that the consolidated source be stored in src/docs/asciidoc/asciidoclet-guide.adoc within this project. That way it can more easily be kept in sync with the latest version of the code.

On the publication/distribution side, I'm looking for guidance from @mojavelinux and @johncarl81 as to what they think is best. I like the idea of having a nicely rendered and styled Asciidoclet Guide that can be linked to from the README, release notes, etc. I don't understand the publication/aggregation process for Asciidoctor.org and if it can pull content from this repository. Are there plans to use Antora going forward?

I use asciidoctlet in JFXtras and am very pleased with it. Recently Maven central required all jars to be accompanied with a source jar and javadoc jar. Beside the component jars, JFXtras also releases an all-in-one jar, which now requires a source and javadoc jar. I'm not very fluent in Gradle, but apparently asciidoctor cannot use multiple source locations so to generate one big javadoc. Is this easily added?

There are 2 phases of implementation for supporting Java 9 and later.

1. Run under Java 9 and later (but build using Java 7/8) -- this was completed and released as AsciiDoclet 1.5.6.

• Fix stylesheet frame issue - #72
• Fix stylesheet warning - #73

2. Build under Java 9/10/11 (presumably using the new Doclet API)

• Port to new Doclet API - #71 -- PR #96
• Get Asciidoctor/JRuby that is module-safe - #80
• Other issues?

Note: We had previously considered an implementation phase of "Run under Java 10 and later (but build using Java 7/8)", but we have decided to directly move to the new Doclet API instead.

Hi

How do others use previous JavaDoc annotation such as @link and @see in the Ascii doc formatted documentation? e.g. if we want to reference another class from a class definition we'd use

{@link classwithpackageidentifier}

Many thanks

Matt

Hello,
Doclint in jdk 8 is very strict. Switching it of is also not a really good idea.

So the question is:

1. Is java 8 supported?
2. I have this entry in my javadoc. According to the asciidoctor docs I don't need to escape the special chracters but javadoc is complaining about the special characters. So who is right here?

/** 
* *Example:*
* [source,xml] 
* --
*                  <executions>
                    <execution>
                        <id>doIt</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
**/ --

Greetings,

would it be possible to create separate files for each comment in order to link it to another Asciidoc-based documentation?

Example use-case:

• I write description of a class, its fields and methods with asciidoc
• Next to it I write general documentation of how to use it
• I want to keep documentation on one place and therefore I want to relate from "general documentation" to class description or field description with "include" directive.
• So asciidoclet could generate files like: "com.acme.SuperClass" containing asciidoc comment and "com.acme.SuperClass#fancyField" containing asciidoc comment on SuperClass' fancyField field in e.g. /target/asciidoc

Would it be possible to hook such behaviour into asciidoclet?

Thanks.

It would be nice if there were a more-or-less official sample demonstrating use of asciidoclet in a Gradle project.

I did find this one: https://github.com/JGrenier/asciidoclet-sample

(One of the reasons I ask for this is that it's very useful for comparison purposes when you think you've found an issue.)

kotlin script is now the default for gradle. I think the readme should have an example for that. This seems to use a lot of magic expectations.

I am trying to use asciidoclet in command line:

javadoc ... -doclet org.asciidoctor.Asciidoclet -docletpath doclet/asciidoclet-1.5.0.jar ...

And I get:
javadoc: error - In doclet class org.asciidoctor.Asciidoclet, method optionLength has thrown an exception java.lang.reflect.InvocationTargetException
java.lang.NoClassDefFoundError: com/google/common/collect/ImmutableList

Any idea? Thanks in advance

I'd like to align the option names that go in additionalparam with the asciidoctor command.

I'm proposing the following changes.

1. Prefer double dash (--) instead of single dash (-) prefix for long option names
2. Use names from the asciidoctor command when there's a matching option
3. Use the same parsing logic for the attribute string (or allow attributes to be specified using multiple -a options)

The mapping would be as follows:

• -include-basedir => --base-dir or -B
• -d => --destination-dir or -D
• -stylesheetsfile => --stylesheet (file is assumed)
• -attributes => --attributes

We want to reenforce knowledge of AsciiDoc option across the ecosystem.

When I enable Asciidoclet on a Java 9 build, the frame sizing/formatting gets messed up:

Removing the Asciidoclet doclet eliminates the problem.

We should probably go ahead and release the current version. Maybe we want to bump the version to 1.5.6 so it matches the version of Asciidoctor it uses (until we have a solution for Issue #70)

(We also have to think about Asciidoclet v2.0 which will require Java 9 or later -- so maybe we'll need to start decoupling Asciidoclet versions from Asciidoctor versions)

Changes since 1.5.4:

• Upgrade to Asciidoctor 1.5.6
• Basic support for running under Java 9 (Java 9 stylesheet support)
• Added env-asciidoclet and env=asciidoclet attributes

@johncarl81 @mojavelinux -- what do we need to do before releasing this?

It looks like the include::some-file.txt[] macro only works for files that I make javadoc copy over into the target/site/apidocs/ directory, which would be stuff in the src/main/javadoc/resources/**/doc-files directories. And then only if I explicitly enable this with by adding a <docfilessubdirs>true</docfilessubdirs> configuration to the maven-javadoc-plugin plugin in my pom.xml file.

It would be really helpful if at least the test-sources directory became available to include from, because then the example code I include will be checked by the compiler on build.

I have asciidoctorj and asciidoctorj-diagram in my pom.xml to generate maven site documentation. How do i configure asciidoclet to use these versions, too?

I've used AsciiDoctor for a while, but am currently using Asciidoclet for the first time. It hasn't been clear where the best place to go for information is.

Currently, it seems the (two?) major sources of "user guide" or "getting started" information are:

• Github project README
• Asciidoclet 1.5.0 release blog entry

Problems with the README:

• No build instructions
• No link to JavaDoc (#46 )
• Is arguably too long

My suggestion is to create a "User's Guide" in a doc folder in this repository. We can move some content from the README and (more important) the 1.5.0 release announcement into the User's Guide and then add build instructions, links to the JavaDoc, etc. to the README. The question, then, is where to put the rendered user's guide.

p.s. I'm willing to help with this work.

Hello I am wondering if there is a way to pass Asciidoctor parameters through Asciidoclet. I am asking because I would like to do something like:

/**
* javadoc
*
*  _{target}_ this is the output directory of Maven
*
**/
code

so what I want to do is to pass the target directory location inside Asciidoclet processor and then be added as Asciidoctor attribute. I don't know if this is possible or not, but for what I have understand for code (sorry I have never develop a doclet) it seems that now it is not implemented.

I am on the verge of using Asciidoclet on a relatively large codebase, that has a lot of old-ish Javadoc written with html. I'd like to progressively enhance the docs, but I can't realistically go and convert all of the existing doc.
Is there any way to make Asciidoclet more lenient ? Perhaps something along the lines of "if there is html in the doc, let it be processed by the default doclet" ?

I am not familiar with how doclets work (i.e what input they get from the Javadoc tool), so this is perhaps more trouble than it's worth. I'd give it a shot though, if one of the devs of Asciidoc would indicate this is something they'd agree is useful. (although this might be quite tricky, since one might want html in their asciidoc, e.g code samples)

Alternatively, perhaps there are tools to help converting existing Javadoc ?

Incorporating code blocks can be tricky as they quickly become out-of-sync with the live code. This is mitigated by referencing real compiled code via the existing Asciidoctor range support

Example:

/**
 * [source,java]
 * --
 * include::Example.java[tags=snippet]
 */
public class Example.java {
    //tag::snippet[]
    public void includeMe(){}
    //tag::snippet[]
}

would results in teh following main javadoc:

public void includeMe(){}

Related to: asciidoctor/asciidoctor#226

The forward slash character can potentially end the Javadoc comment prematurely. Typically it is escaped using {@literal /}. However, since we've got attributes in AsciiDoc, this can be simplified to {slash}. Although AsciiDoc has built-in named replacements like backslash, it does not have slash.

The new attribute can be defined when calling the Asciidoctor render method:

attribute("slash", "/")

An example use case is as follows:

[source,java]
--
/**
 * Javadoc in example code
 *{slash}
public class ExampleCode {}
--

The only catch is that attributes aren't normally substituted in verbatim blocks like source. One workaround is to manually replace the {slash} prior to invoking Asciidoctor.render. (That's currently how the {@literal *} is handled).

Another possible solution is to replace an escaped forward slash prior to invoking Asciidcotor.render.

 *\/

would become

 */

It's an interesting use case, definitely worth exploring.

Btw, the author always has the option of defining the attribute and enabling attribute substitution on the source block, as in:

= Javadoc for Class
:slash: /

[source,java,subs="specialcharacters,attributes,callouts"]
--
/**
 * Javadoc in example code
 *{slash}
public class ExampleCode {}
--

It would be great to have a curated list of Asciidoclet-powered projects somewhere. We can use this issue to collect a list and I'll put together a pull request to put them somewhere.

I did find this Google+ post by @mojavelinux

I run building of my project with 1.5.4 and 1.5.6.

When I run building with 1.5.4 it works OK: processes all sources, create plantuml diagram.

When I rum building with 1.5.6 I get error:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.0.1:jar (attach-javadocs) on project contract: MavenReportException: Error while generating Javadoc:
[ERROR] Exit code: 1 - javadoc: error - In doclet class org.asciidoctor.Asciidoclet, method start has thrown an exception java.lang.reflect.InvocationTargetException
[ERROR] java.lang.NoClassDefFoundError: org/jruby/exceptions/RaiseException
[ERROR] at org.asciidoctor.Asciidoctor$Factory.create(Asciidoctor.java:695)
[ERROR] at org.asciidoctor.asciidoclet.AsciidoctorRenderer.(AsciidoctorRenderer.java:62)
[ERROR] at org.asciidoctor.Asciidoclet.run(Asciidoclet.java:273)
[ERROR] at org.asciidoctor.Asciidoclet.start(Asciidoclet.java:268)
[ERROR] at org.asciidoctor.Asciidoclet.start(Asciidoclet.java:242)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
[ERROR] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
[ERROR] at java.lang.reflect.Method.invoke(Method.java:498)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:310)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:189)
[ERROR] at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:366)
[ERROR] at com.sun.tools.javadoc.Start.begin(Start.java:219)
[ERROR] at com.sun.tools.javadoc.Start.begin(Start.java:205)
[ERROR] at com.sun.tools.javadoc.Main.execute(Main.java:64)
[ERROR] at com.sun.tools.javadoc.Main.main(Main.java:54)
[ERROR] Caused by: java.lang.ClassNotFoundException: org.jruby.exceptions.RaiseException
[ERROR] at java.net.URLClassLoader.findClass(URLClassLoader.java:382)
[ERROR] at java.lang.ClassLoader.loadClass(ClassLoader.java:424)
[ERROR] at java.lang.ClassLoader.loadClass(ClassLoader.java:357)
[ERROR] ... 16 more

As far as I understand Asciidoctor could not initialize properly. But I cannot get why as it misses some jruby classes.

Maven: 3.6.0
Java: 1.8.0_202
Asciidoclet: 1.5.6

Maven javadoc plugin's configuration

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-javadoc-plugin</artifactId>
	<version>${javadoc-plugin.version}</version>
	<configuration>
		<source>${java.version}</source>
		<overview>src/main/javadoc/overview.adoc</overview>
		<doclet>org.asciidoctor.Asciidoclet</doclet>
		<docletArtifact>
			<groupId>org.asciidoctor</groupId>
			<artifactId>asciidoclet</artifactId>
			<version>${asciidoclet.version}</version>
		</docletArtifact>
		<additionalOptions>
			--base-dir ${project.basedir}/src/main/javadoc
			--attribute "name=${project.name}"
			--attribute "version=${project.version}"
			--attribute "title-link=${project.url}[${project.name} ${project.version}]"
			--require asciidoctor-diagram
			--gem-path ${env.GEM_HOME}
			--attribute data-uri
		</additionalOptions>
		<!--
		<additionalDependencies>
			<additionalDependency>
				<groupId>org.jruby</groupId>
				<artifactId>jruby</artifactId>
				<version>9.2.5.0</version>
			</additionalDependency>
		</additionalDependencies>
		-->
		<!--
		<additionalDependencies>
			<additionalDependency>
				<groupId>org.asciidoctor</groupId>
				<artifactId>asciidoctorj-diagram</artifactId>
				<version>1.5.12</version>
			</additionalDependency>
		</additionalDependencies>
		-->
	</configuration>
	<executions>
		<execution>
			<id>attach-javadocs</id>
			<goals>
				<goal>javadoc-no-fork</goal>
				<goal>jar</goal>
			</goals>
		</execution>
	</executions>
</plugin>

I have tried add jruby and asciidoctor as additional dependencies - it still doesn't work for 1.5.6.
Also I have tried both javadoc and javadoc-no-fork goals.

I want to write a mathematical formula in JavaDoc. I writed it as following

The overall run time complexity should be latexmath:[O(log(m+n))].

And, I set the attribute as following:

<additionalparam>
    --base-dir ${project.basedir}

    --attribute "stem=latexmath"

    --attribute "name=${project.name}"
    --attribute "version=${project.version}"
</additionalparam>

But, it did not generate the formula:

The overall run time complexity should be \(O(log(m+n))\).

It seems to be no import JavaScript Library.

When running Asciidoclet under Java 9 I get the following message

javadoc: warning - The old Doclet and Taglet APIs in the packages
com.sun.javadoc, com.sun.tools.doclets and their implementations
are planned to be removed in a future JDK release. These
components have been superseded by the new APIs in jdk.javadoc.doclet.
Users are strongly recommended to migrate to the new APIs.

At some point Asciidoclet should be ported to the new API.

When building JavaDoc with Asciidoclet on Java 9, I get the following warning:

WARNING: Illegal reflective access by org.jruby.util.io.ChannelDescriptor (file:/Users/sean/.gradle/caches/modules-2/files-2.1/org.asciidoctor/asciidoclet/1.5.5-SNAPSHOT/9cede66f20a469bf798caa5af9495e8857e9741e/asciidoclet-1.5.5-SNAPSHOT.jar) to method sun.nio.ch.SelChImpl.getFD()
WARNING: Please consider reporting this to the maintainers of org.jruby.util.io.ChannelDescriptor

This looks like an upstream issue (JRuby) but I thought I'd create an issue here to remind us to upgrade to a newer Asciidoctor/JRuby when available and to perhaps create an issue on Asciidoctor if there isn't one already.

I'm not sure if I should post this here or in asciidoctorj, so please move it if it's more appropriate there.

I use Asciidoctor to generate technical documentation and prefer all of it to be of the same style. My main documentation pages are rendered using prettify as source highligher, unfortunately though Asciidoclet does not provide this option.

Per discussion in #87, the comprehensive of the README.adoc lends some confusion to the documentation, i.e., as if it's in multiple locations. The main structure and content of that doc has been added to the universal asciidoctor docs page which can be extended as needed. The README.adoc could be simplified to focus on the overview.

This would ease custom processing for Javadoc, e.g. with ifdef::.

Hi guys,

I am very interested in using asciidoclet in our project (Vert.x), but I notice the latest release was 0.1.4 some 6 months ago.

Is it still in active development? If it's complete, any chance of a 1.0 release?

https://github.com/JGrenier/asciidoclet-sample is nice, but we should have a similar project under the asciidoctor organization that we can keep up to date and integrate with CI tools for testing and demonstration purposes.

One of the attendees at Devoxx France proposed the idea of having an option in Asciidoclet to export all AsciiDoc doc strings to disk (i.e., export-docstrings). Exporting the strings would allow the content to be reused in other context or by other tools.

I really like this idea as a way to keep content DRY, especially if Javadoc is being treated as the canonical source of information for a portion of the documentation. It's the inverse strategy to using the include tag.

I imagine that each doc string would be exported to a file that is named according to where the doc string originated (package name + [class name] + [method name]). These files would be exported to the build output adjacent to the javadoc directory.

Noticed this while working on #20 (overview file support). Thought it was my fault at first, but it's a general problem between Asciidoctor's HTML output and javadoc's generation of package overview pages.

If your package (or overview) comment (in Asciidoc) starts with anything other than a level 0 heading, then javadoc gets confused when it tries to extract the first sentence, and ends up putting <div>s in the wrong place in the final package-summary.html or overview-summary.html pages.

For example, asciidoclet's own org/asciidoctor/package-info.java currently starts with:

/**
 * = Asciidoclet
 *
 * https://github.com/asciidoctor/asciidoclet[Asciidoclet] is a Javadoc Doclet...

and gets generated correctly. The structure of org/asciidoctor/package-summary.html looks something like this:

<!-- ========= END OF TOP NAVBAR ========= -->
<div class="header">...</div> 
<div class="contentContainer">...</div>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav">...</div>
<div class="subNav">...</div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->

But if I change the first line of the package comment to be plain text:

/**
 * Asciidoclet
 *
 * https://github.com/asciidoctor/asciidoclet[Asciidoclet] is a Javadoc Doclet...

...then org/asciidoctor/package-summary.html comes out like this:

<!-- ========= END OF TOP NAVBAR ========= -->
<div class="header">
    <h1 title="Package" class="title">Package&nbsp;org.asciidoctor</h1>
    <div class="docSummary">...</div>
    <div class="contentContainer">...</div>
    <!-- ======= START OF BOTTOM NAVBAR ====== -->
    <div class="bottomNav">...</div>
    <div class="subNav">...</div>
    <!-- ======== END OF BOTTOM NAVBAR ======= -->

I.e. all of the remaining content ends up inside the <div class="header">.

Something to do with the way javadoc extracts the first sentence of a comment is breaking on Asciidoctor's HTML output, causing the header div to not be closed properly. The output is still readable but the formatting is a bit off and some styling won't work since the document structure is incorrect.

It seems to be OK when the first line is a level 0 heading because this comes out in its own <h1> element, not nested inside <div>s, so I guess javadoc is able to handle it. Having said that, even these will break if javadoc's "breakiterator" option is enabled.

You can work around this by putting the first sentence of a package or overview comment in a passthrough block:

/**
 * ++++
 * Asciidoclet.
 * ++++
 *
 * https://github.com/asciidoctor/asciidoclet[Asciidoclet] is a Javadoc Doclet...

However this does mean any formatting or links you might want in the first sentence would have to be done as HTML, which is a pity!

Edit: end the sentence in the passthough block with a full stop, or surround with <p> or header tags, so that javadoc can recognize the end of the sentence correctly.

Hello,

I have a question regarding integration of asciidoclet with groovydoc. Looks like groovydoc utility doesn't accept doclet class as a parameter.

Is it possible to do?

Thanks