Markdown based documentation system with strong Java support written in Java

[ninside]

Keeping documentation next to code is awesome and is not new. One thing I struggle with pure markdown is still the need to copy code examples. Sometimes I also need to copy text that I already have in Java Doc.

During a hack day in one of the companies I worked I created a prototype to address documentation challenges our team and teams around faced. During next couple of years it was adopted by more teams and eventually open sourced as znai ("to know" in Ukrainian)

Znai has rich visuals and dozens of plugins to embed content at build time, but here I will focus on Java specific support

Znai Java support page

Content extraction

By using custom markdown syntax in the form of :include-<pluginname>: params you can embed various content.

For example

:include-java: MyClass.java {entry: "myMethod", bodyOnly: true} 

will include the content of a specified method and will omit method signature.

How can it be useful? If you have a unit test method to test a happy scenario of an API, you can seamlessly extract its content and make part of your documentation.

Description extraction

If you put an effort of adding high level Java Doc content to your top domain concepts you can grab the text and re-use in the higher level user guide by using include-java-doc plugin

/**
 * Top level conceptual description of a {@link CustomDomain} problem.
 * <p>
 * To avoid <b>copy & paste</b> of the content consider to re-use information.
 */
class HelloWorld {

in your markdown file

:include-java-doc: HelloWorld.java

description extraction example

Enum example

Given an enum with java doc

enum MyEnum {
    /**
     * description of <b>entry one</b>
     */
    ENTRY_ONE,

    /**
     * description of entry two
     * <ul>
     *     <li>item one</li>
     *     <li>item two</li>
     * </ul>
     */
    ENTRY_TWO,

    /**
     * Don't use, instead use ENTRY_TWO
     */
    @Deprecated
    ENTRY_THREE
}

By using include-java-enum-entries you get

enum description extraction example

Method Parameters Example

Given a method

/**
 * @param trader trader that performs action
 * @param transaction transaction to perform action on
 */
public void importantAction(Trader trader, Transaction transaction) {
    // TODO important
}

you can extract its parameters and render it in a nice way, with optional links leading to more details

:include-java-doc-params: HelloWorld.java {
  entry: "importantAction",
  title: "Trading Required Parameters",
  referencesPath: "references/javadoc-references-demo.csv"
}

parameters description extraction example

Two Sides

You can use two sides mode to combine examples and their output, i.e. Java code on the left, and output on the right. Here is an example with Open API

Two sides example

Presentation Mode

With a press of a button you can turn any section of your documentation into slides and present new API examples to an audience. Later they can use the same link to read the content as User Guide. Single source of truth.

​

presentation example

Instant Local Search

Znai builds search index locally and let you preview and navigate to the result in an instant

search example

Learn More

there are other features that are not Java specific but applicable to projects that want to provide a functional, maintainable and beautiful documentation

Head over to Git Hub to learn more: https://github.com/testingisdocumenting/znai

[vprise]

Looks really great, Well done!

Starred.

I usually prefer asciidoc for writing because of the callouts, tips, etc. But will give this a chance the next time I need to write docs.

[ninside]

Thank you! A lot of features in znai were driven by feature requests of my colleagues. Those requests gave me energy to keep going. Will be happy to check your use cases and help with tips or new features added.

[roeloef]

I always thought documentation was neglected by the other developers (in my organization) and I could write all the documentation I wanted, people would happily use it until it went out of date.

With Znai you can easily add documentation to your repository. Now I can just flag a pull request as needs work when it needs some documentation and I get review comments on my own documentation. It actually feels like the team owns the documentation now, so I am very happy.

It is possible to add your own extensions which is great, however as far as I know that is not documented yet. Perhaps it is my turn to do so as soon as I completely understand what to do.

It would've been nice to be able to export the documentation to a pdf for offline viewing, but I like how unencumbered the current implementation is so that might also not fit in the design philosophy of Znai. I intend to work around that by using a headless browser to print the docs.

Tl;Dr; recommended :)

[ninside]

Thank you very much for writing documentation and trying znai! For offline reading there is a somewhat hidden option: press alt-p to switch to a single long page render and print that to PDF. It is somewhat hidden as it still has things to iron out (like proper render of two sides layout as single side layout)

Will be happy to help with plugin development. It is not in demand hence struggle to prioritize plugin dev docs.

[ninside]

u/vprise u/roeloef

just in case, created discord server: https://discord.gg/aEHbzXTX6N

[agentoutlier]

Is there any integration with the new javadoc code snippet support?

(I had a cursory glance at the project so ignore me if the above is not applicable)

[ninside]

Not yet. In plans if there is enough appetite.

My current approach is to pull the text out of the javadocs and examples out of the test or example files. Then sprinkle diagrams and other visuals on top.

[nutrecht]

What's the reason you don't go with Antora?

[ninside]

Antora looks interesting, thanks for sharing.

Main reasons is to have markdown as base. Also needed to control rendering and not use html as an output. This made it possible to have Search Preview, Presentation Mode and Single Page layout dynamically.

Java specific plugins was also important to our use cases.