Gradle Mkdocs plugin

Additional

Language
Groovy
Version
1.0.0 (Dec 30, 2017)
Created
Dec 20, 2017
Updated
Dec 30, 2017
Owner
Vyacheslav Rusakov (xvik)
Contributor
Vyacheslav Rusakov (xvik)
1
Activity
Badge
Generate
Download
Source code

Blurb

Gradle Mkdocs plugin

About

Generates project documentation with Mkdocs python tool.

Example documentation (generated and published with the plugin).

Ideal for open source projects:

  • Easy start: initial docs source generation
  • Markdown syntax (with handy extensions)
  • Great look from material theme (used by default) with extra features:
    • Mobile friendly
    • Embedded search
    • Syntax highlighting
  • Easy documentation contribution (jump to source)
  • Multi-version documentation publishing to github pages
Summary
  • Configuration: mkdocs
  • Tasks:
    • mkdocsInit - generate initial site
    • mkdocsServe - livereload server (dev)
    • mkdocsBuild - build documentation
    • mkdocsPublish - publish to github pages
    • type:MkdocsTask to call custom mdocs commands
  • Enable plugins: git-publish, use-python

Setup

Releases are published to bintray jcenter, maven central and gradle plugins portal.

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'ru.vyarus:gradle-mkdocs-plugin:1.0.0'
    }
}
apply plugin: 'ru.vyarus.mkdocs'

OR

plugins {
    id 'ru.vyarus.mkdocs' version '1.0.0'
}

Python

Requires installed python 2.7 or 3.3 and above with pip.

Check and install python if required.

Usage

By default, documentation source assumed to be in src/doc.

To change location:

mkdocs {
    sourcesDir = 'docs' 
}

Call mkdocsInit task to generate initial site version into src/doc (default):

src/doc/
    docs/               - documentation source
        ...
        index.md
    mkdocs.yml          - site configuration

Call mkdocsServe task to start live reload server: look generated default docs ( http://127.0.0.1:8000/).

WARNING Python process will not be killed after you stop gradle execution. This is a known gradle problem and the only known workaround is to start task without daemon: gradlew mkdocsServe --no-daemon. Another alternative is to start serve command directly: copy console command from task execution log and use it directly.

Initial site configuration

Note: plugin does not use mkdocs new command for site generation: custom template used with pre-configured plugins and enabled material theme.

Open generated mkdocs config file src/doc/mkdocs.yml. It contains many commented options:

Commented option Recommendation
site_author fill with you name or remove (appear in meta tags only)
site_url Set to documentation root url (gh-pages url). Used as meta tag, as a link on the home icon and inside generated sitemap.xml. NOTE plugin will automatically modify url to point to correct published folder (when multi-version publication used).
Repository link on each page (right top corner)
repo_name Source repository link text (by default set to project name)
repo_url Repository url (Github or Bitbucket)
edit_uri Path to documentation source in the source repository (required for "edit page" (pencil icon) link)
Copyright
copyright Shown below each page

For material theme configuration see: configuration docs. Note that most useful material theme extensions are already enabled (see markdown_extensions section).

Writing

Yaml configuration pages section declares your documentation structure. Pages inside docs folder may be structured as you want.

To add new page simply add new markdown file (page.md) and add reference to it in pages config.

Read:

Building

By default, mkdocsBuild task will generate (suppose project version is '1.0-SNAPSHOT'):

build/mkdocs/
    /1.0-SNAPSHOT/    - mkdocs site
    index.html        - redirect to correct site

Plugin is configured for multi-version documentation publishing: each version is in it's own folder and special index.html at the root will redirect to the latest version (when published).

Everything in build/mkdocs/ is assumed to be published into github pages.

Default configuration:

mkdocs.publish {
    docPath = '$version'  
    rootRedirect = true  
}

As documentation is often updated for already released version, it makes sense to define current version manually (or define it when you need to publish to exact version):

mkdocs.publish.docPath = '1.0'

When older documentation version needs to be updated switch off redirection index.html generation (so it would not override redirection to the latest version):

mkdocs.publish {
    docPath = '0.9'  
    rootRedirect = false  // site root must still redirect to '1.0' (assume it's already published)
}

Will build:

build/mkdocs/
    /0.9/    - mkdocs site for old version

Publication layouts

You may define whatever layout you want, e.g.:

mkdocs.publish.docPath = 'en/1.0/'  

Here generated site will be published into /en/1.0/ folder (not just version) and index.html generated at the root with correct redirection.

Single version site

If you don't want to use multi-version support at all then:

mkdocs.publish.docPath = ''  // or null 

This way, mkdocs site will always be published at the root (in case of publish it will always replace previous site version).

site_url

site_url configuration defined in mkdocs.yml should point to the site root. It may be github pages or some custom domain. Setting affect home icon link, page metadata and links in genearted sitemap.xml.

When multi-version publishing used (by default), this url must point to documentation version folder (otherwise links will be incorrect in the sitemap). To avoid manual changes, just configure root site url (e.g. http://myroot.com/) and plugin will automatically change site_url before mkdocsBuild (for example, to http://myroot.com/1.0/; see build log - it will show updated url). Config is reverted back after the task, so you will not have to commit or revert changes.

If site_url option is not defined at all (or multi-version publishing is not enabled) then config will not be changed.

You can disable automatic configuration changes:

mkdocs.updateSiteUrl = false

Note that mkdocsServe is not affected (will generate with the original site_url) because it is not important for documentation writing (you can always call mkdocsBuild and validate urls correctness).

Configuration

Configuration properties with default values:

mkdocs {
    // mkdocs sources
    sourcesDir = 'src/doc'    
    // strict build (fail on build errors)
    strict = true    
    // target build directory (publication root)
    buildDir = 'build/mkdocs'
    // automatically update site_url in mkdocs.yml before mkdocsBuild
    updateSiteUrl = true
    
    publish {
        // publication sub-folder (by default project version)
        docPath = '$version'        
        // generate index.html' for root redirection to the last published version 
        rootRedirect = true
        // publish repository uri (bu default the same as current repository)
        repoUri = null
        // publication branch
        branch = 'gh-pages'
        // publication comment
        comment = 'Publish $docPath documentation'
        // directory publication repository checkout, update and push
        repoDir = '.gradle/gh-pages'
    }
}

Publication

Plugin does not use mkdocs publication, because it does not support multi-versioning. Instead, git-publish plugin is used for publication.

By default, no configuration is required. Only project itself must be published to git so that plugin could calculate default url (or mkdocs.publish.repoUrl manually specified).

On the first mkdocksPublish task call:

  • gh-pages branch will be created in the same repo
  • built site pushed to gh-pages repository branch

Later mkdocsPublish task calls will only remove current version folder (replace with the new one) or publish completely new version only.

You can find actual gh-pages branch inside .gradle/gh-pages (this checkout is used for publishing). Gradle folder is used to cache repository checkout because eventually it would contain many versions and there is no need to checkout all of them each time (folder could be changed with mkdocs.publish.repoDir).

Authentication

By default, git-publish will ask credentials with a popup (swing). Even if github pages are published on the same repo, the repo is checked out into different folder and so current repository credentials can't be used automatically.

You can specify credentials as:

  • Environment variables: GRGIT_USER (could be github token), GRGIT_PASS
  • System properties: org.ajoberstar.grgit.auth.username (could be github token), org.ajoberstar.grgit.auth.password
  • Ssh key properties: org.ajoberstar.grgit.auth.ssh.private (path to key), org.ajoberstar.grgit.auth.ssh.passphrase

See details in grgit docs.

Plugin will automatically bind gradle properties org.ajoberstar.grgit.auth.* to system properties (just before gitPublishReset). This allows you to define credentials as global gradle properties in ~/.gradle/gradle.properties:

org.ajoberstar.grgit.auth.username=user
org.ajoberstar.grgit.auth.password=pass

For testing, you can define properties inside gradle script:

ext['org.ajoberstar.grgit.auth.username'] = 'user'
ext['org.ajoberstar.grgit.auth.password'] = 'pass'  

Publish additional resources

If you want to publish not only generated site, but something else too then configure git-publish plugin to include additional content.

For example, to include javadoc:

gitPublish.contents {
    from(javadoc) {
        // need to use resolveDocPath because by default it's a template 
        into "\${mkdocs.resolveDocPath()}/javadoc"
    }
}

// dependency will NOT be set automatically by copySpec above
gitPublishReset.dependsOn javadoc

With this configuration, calling mkdocsPublish will publish generated mkdocs site with extra javadoc folder inside (you can put relative link to it inside documentation).

Advanced publishing configuration

To be able to configure advanced cases, you need to understand how everything works in detail.

Here is how git-publish plugin is configured by default:

gitPublish {

    repoUri = mkdocs.publish.repoUri
    branch = mkdocs.publish.branch
    repoDir = file(mkdocs.publish.repoDir)
    commitMessage = mkdocs.publish.comment

    contents {
        from("${mkdocs.buildDir}")
    }

    if (multi_version_publish) {
        preserve {
            include '**'
            exclude "${mkdocs.publish.docPath}/**"
        }
    }    
}

Customized tasks dependency chain:

mkdocsBuild <- gitPublishReset <- gitPublishCopy <- gitPublishCommit <- gitPublishPush <- mkdocsPublish

Publication process:

  1. mkdocsBuild build site into $mkdocs.buildDir/$mkdocs.publish.docPath (by default, build/mkdocs/$version/)
    • root redirect index.html generated (by default, build/mkdocs/index.html)
  2. gitPublishReset clones gh-pages repo (by default, into .gradle/gh-pages) or creates new one
    • cleanup repo according to gitPublish.preserve (by default, .gradle/gh-pages/$version/ folder removed only)
  3. gitPublishCopy copies everything according to gitPublish.contents (by default, everything from build/mkdocs)
  4. gitPublishCommit, gitPublishPush - commit changes and push to gh-pages repository (by default, gh-pages branch in current repo)

You can configure additional folders for publication with contents (as shown above with javadoc) and cleanup extra directories with preserve configuration. For example:

gitPublish {
    contents {
        from 'build/custom-dir' {
            into 'custom-dir'        
        }
    }
    
    preserve {
        exclude 'custom-dir'
    }
}

Here extra build/custom-dir directory added for publication (into custom-dir) and previous custom-dir folder (already committed) will be removed before publication.

Pip modules

Plugin will install by default the following pip modules:

By default, modules are installed into project specific virtualenv. You can see all installed modules with pipList task.

If you want to use other python modules (e.g. other theme):

python.pip 'other-module:12', 'and-other:1.0'

Also, you can override default modules versions:

python.pip 'mkdocs:18.0'

And even downgrade:

python.pip 'mkdocs:16.0'

You can use pipUpdates task to check if newer module versions are available.

Custom Mkdocs task

If you need to use custom mkdocs command:

task doSomething(type: MkdocsTask) {
    command = '--help'
}

:doSomething task call will do: python -m mkdocs --help.

Might also like