Note: this repo is being merged into openrndr-guide and won't be maintained in the future.

DokGen

DokGen is a gradle plugin that takes kotlin source files such as this and turns it into documentation like this. The kotlin sources are turned into markdown which are then used to generate a static site using docsify. Using DokGen, you can take advantage of IDE features like auto-completion and refactoring while writing documentation. Moreover, your docs will always be up to date with your API, because invalid docs will just not compile.

Read this medium article on how we've improved the OPENRNDR guide using DokGen.

Getting started

Add DokGen to your build.gradle through jitpack.

// add jitpack to repositories (both to the buildscript and top-level repositories)
maven { url 'https://jitpack.io' }


// add DokGen to the buildscript dependencies
classpath 'com.github.openrndr:dokgen:bdc8d110d4'


// add DokGen to the top-level dependencies
implementation 'com.github.openrndr:dokgen:bdc8d110d4'

Have a look at this gradle file. An example repository showing basic usage and setup can be found here. A more complete setup can be seen in the OPENRNDR guide repo.

Annotations

Text

@Text
"""
# Some Arbitrary Markdown
"""

Strings annotated with @Text may contain arbitrary markdown. The annotated strings are copied unmodified to the target file.

Application

@Application
run {
  println("Hello World")
}

Code annotated with Application is wrapped in a main function and exported to its own file src/generated/examples. DokGen will run these application examples during the build process to make sure they work.

This will create a file roughly:

fun main(args: Array<String>) {
    println("Hello World")
}

Code

@Code
fun foo(){
  println("Hello World")
}

Use this annotation to show code snippets in the documentation.

Code.Block

@Code.Block
run {
  println("Hello World")
}

Use this annotation to include the contents of a run block in the documentation. This will produce the following:

println("Hello World")

Exclude

run {
  println("hello")

  @Exclude
  println("world")
}

Use this annotation to exclude parts of the code from the documentation. This will produce the following:

run {
   println("hello")
}

Media.Image

@Media.Image "media/myimage.png"

Include an image in the documentation.

Media.Video

@Media.Video "media/myvideo.mp4"

Include an video in the documentation.

File names and titles

Titles from which the navigation sidebar is generated are derived from the file names. To determine the order of files, include a number sequence in the beginning of the filename, for example C00MyFile.kt, C01MyFile.mt. Words in the file names can be either snake or camel cased: both "My_File" and "MyFile" will become "My File" in the sidebar. Additionally, file names can be defined in an index.properties file placed in the same directory as the files it belongs to. The contents of the index.properties file is a simple mapping between the file name (without extension) and the desired title as it should appear in the sidebar. For example the following would work when placed next to files C00MyFile.kt and C01MyFile2.kt:

C00MyFile = Title
C01MyFile2 = Title2

Gradle tasks

DokGen provides the following gradle tasks under the group dokgen:

dokgen

Runs the build process.

serveDocs

Starts a development server and makes the docs available at http://localhost:3000. You need docker installed for this to work.

Configuration example

dokgen {
    runner {
        if (System.properties['os.name'] == "Mac OS X") {
            // pass jvm arguments to the process that will run the exported examples
            jvmArgs = ["-XstartOnFirstThread"]
        }
    }

    examples {
        // set the web url of where the examples will be accessible
        webRootUrl = "https://github.com/openrndr/openrndr-examples/blob/master/src/main/kotlin"
    }

    docsify {
        // media files to copy
        media = [file("$projectDir/media"), file("$projectDir/static-media")]

        // assets to copy
        assets = [file("$projectDir/data/docsify-assets")]
    }
}

Example

Docsify assets

Include any of the following files in your docsify assets:

index.html: override the default one
index.js: override the default one
CNAME: for setting up a custom subdomain on GitHub.

Example

Publishing

DokGen doesn't come with a built-in publishing solution. gradle-git-publish is an easy to use gradle plugin for this purpose.

openrndr / dokgen Goto Github PK

dokgen's Introduction