gradle-docs

Table of Contents

1. Compatibility
2. Build
- 2.1. Publishing
3. Usage
- 3.1. Tasks
4. Jinja2 Context Map
5. Tasks
6. Configuration
7. Jekyll Website
- 7.1. Website Dockerfile
8. Testing during development
9. Licenses

Applies brightSPARK Labs standardisation to project documentation.

1. Compatibility

Plugin Version	Gradle Version	Java Version
6.x.y	9.x.y	21
5.x.y	9.x.y	17
4.x.y	8.x.y	17
3.x.y	8.x.y	17
2.x.y	7.x.y	17
1.x.y	6.x.y	11

2. Build

./gradlew build

2.1. Publishing

To publish a new version:

If bumping Java, then ensure the right version is specified in .github/ files.
Use git flow to merge it into master.
Push master and the CI server will publish via ./gradlew publishPlugins.

3. Usage

// file: build.gradle

plugins {
    // Applies brightSPARK Labs standardisation to project documentation.
    id 'com.brightsparklabs.gradle.docs' version '<version>'    (1)
}

// Define repositories to ensure plugin dependencies libraries can be resolved.
repositories {
    mavenCentral()
}

Latest version:

By default:

AsciiDoc files should be stored under src/docs/.
- Any of the extended HTML colours can be used and will render in the PDFs. The colour name should be completely in lowercase. E.g.
  [.lime]#This is lime# icon:circle[role=navy, size=4x] A navy circle
  Will render as:
  
  This is lime
  
  [circle] A navy circle
Images should be stored under src/images, which can then be referenced via AsciiDoc image macros.
Any files ending with .j2 will first be processed by Jinjava (Java port of Python Jinja2).
A number of Jinja2 macros are added by default. See brightSPARK Labs Jinja2 Macros.

Running ./gradlew build will generate PDF and HTML of the documentation.

If docker buildx is present on the system, then in addition to the AsciiDoc HTML backend output, it will also generate a Jekyll based static website.

3.1. Tasks

The tasks added by this plugin appear under the BrightSPARK Labs - Docs tasks group.

Example 1. Listing tasks

$ ./gradlew task | sed -n '/BrightSPARK/,/^$/p'

BrightSPARK Labs - Docs tasks
-----------------------------
bslAsciidoctor - Alias for `asciidoctor` task.
bslAsciidoctorPdf - Alias for `asciidoctorPdf` task.
bslAsciidoctorPdfInDocker - Runs the Asciidoctor PDF tasks within a Docker container. Useful as
  the CLI diagramming CLI tools do not need to be installed on the local machine.
bslAsciidoctorPdfVersioned - Creates PDF files with version string in filename.
cleanJekyllWebsite - Cleans the Jekyll website out of the build directory.
cleanJinjaPreProcess - Cleans the Jinja2 processed documents out of the build directory.
generateDockerfile - Generates a Dockerfile for hosting the documentation as a static website.
generateJekyllWebsite - Generates a Jekyll based website from the documents using docker.
jinjaPreProcess - Performs Jinja2 pre-processing on documents.

Note	`generateJekyllWebsite` is only available if `docker buildx` is present on the system.

4. Jinja2 Context Map

Each template file is passed to the Jinja2 engine to be rendered into the final file.The template can reference variables defined in a context map (Map<String, Object>). This context map is generated by the system and is dynamic, containing different values based on the template file currently being rendered.

The context map has the following top level keys. Each key is explained in the sections below.

sys	System variables
vars	Global variables
vars_file_last_commit	Global variables
template_file	(Dynamic) Current template file variables
template_dir	(Dynamic) Current template dir variables
instance_file	(Dynamic) Current instance file variables
output_file	(Dynamic) Current output file variables
config	Plugin configuration variables
buildscript_vars	Buildscript variables
env	Environment variables of the host

Template files can reference any of the variables in this map via standard Jinja2 syntax.

Example 2. Template file Jinja2 references

my-file.adoc.j2

{{ sys.project_version }}

{{ output_file.last_commit.timestamp | datetimeformat("%Y-%m-%d at %H:%M %Z", "Australia/Sydney") }}

{{ output_file.last_commit.timestamp_formatted.iso_utc_space }}

Any YAML variables file (see below for all the various locations/names), can also reference any of the other variables in the context map via Jinja2 syntax. This allows much great flexibility than YAML anchors.

Important

The only caveat is that you must explicitly cast the reference to a YAML string.

Example 3. Explicitly cast references to YAML strings.

my-file.adoc.j2.yaml

cast_with_quotes: '{{ sys.project_name }}'

cast_with_block: |
  {{ sys.project_description }}

Example 4. Reference resolution

Variables file with references.

# Standard YAML anchors.
defaults: &default_settings
  access: read-only
  retention: 90
  encryption: AES256

data_hub:
  name: Main Data Vault
  views:
    - name: Intel Holdings
      description: Structured intelligence records
      # Standard YAML references.
      settings: *default_settings
    - name: Case Management
      description: Active and historical case records
      # Standard YAML references with override.
      settings:
        <<: *default_settings
        retention: 180  # overrides the default
    - name: Evidence Ledger
      description: Stored evidentiary data
      # Standard YAML references.
      settings: *default_settings

# ----------------------------------------
# Examples of Jinja2 references.
# ----------------------------------------

uppercase_name: '{{ sys.project_name|upper }}'

first_view_name: '{{ template_file.vars.data_hub.views[0].name }}'

# IMPORTANT: Because references are strings, non-strings become strings.
second_view_retention: '{{ template_file.vars.data_hub.views[1].settings.retention }}'

embed_variable: |
Unlike YAML anchors, you can embed other fields like

  **{{ template_file.vars.data_hub.name }}**

within other variables.

# You can use recursive references.
this_works: '{{ template_file.vars.defaults.access }}'
recursive_reference: '{{ template_file.vars.examples.this_works|capitalize }}'

# IMPORTANT: If you do not case to string it will not work.
this_does_not: {{ template_file.vars.defaults.access }}

Resulting variables file (internally) with references resolved.

# Standard YAML anchors.
defaults:
  access: read-only
  retention: 90
  encryption: AES256

data_hub:
  name: Main Data Vault
  views:
    - name: Intel Holdings
      description: Structured intelligence records
      # Standard YAML references.
      settings:
        access: read-only
        retention: 90
        encryption: AES256
    - name: Case Management
      description: Active and historical case records
      # Standard YAML references with override.
      settings:
        access: read-only
        retention: 180
        encryption: AES256
    - name: Evidence Ledger
      description: Stored evidentiary data
      # Standard YAML references.
      settings:
        access: read-only
        retention: 90
        encryption: AES256

# ----------------------------------------
# Examples of Jinja2 references.
# ----------------------------------------

uppercase_name: 'MY PROJECT'

# If referencing array variables you must wrap reference in quotes.
first_view_name: 'Intel Holdings'

# IMPORTANT: Because references are strings, non-strings become strings. (1)
second_view_retention: '90'

embed_variable: |
Unlike YAML anchors, you can embed other fields like

  **Main Data Vault**

within other variables.

# You can use recursive references.
this_works: 'read-only'
recursive_reference: 'read-only'

# IMPORTANT: If you do not case to string it will not work. (2)
this_does_not: <BUILD FAILS>

The integer field data_hub.views[1].settings.retention is now a string.
The gradle task will fail as the value for this_does_not was not explicitly cast to a string. The following will work (due to the quotes):
this_does_not: '{{ template_file.vars.defaults.access }}'

4.1. `sys` - System variables

The following are added to the Jinja2 context map:

sys:
  # The `project.name` set in Gradle.
  project_name: <name>

  # The `project.description` set in Gradle.
  project_description: <description>

  # The `project.version` set in Gradle.
  project_version: <version>

  # The `project.projectDir.toPath()` set in Gradle.
  project_path: <path>

  # The time the build was run as ZonedDateTime.
  build_timestamp: <timestamp>

  # The time the build was run in different string formats.
  build_timestamp_formatted:
    # Timestamp in UTC as an ISO8601 string.
    iso_utc: <timestamp>

    # Timestamp in UTC as an ISO8601 string with `T` replaced by a space.
    iso_utc_space: <timestamp>

    # Timestamp in UTC as an ISO8601 string with `:` removed (safe for Windows file systems).
    iso_utc_safe: <timestamp>

    # Timestamp with offset as an ISO8601 string.
    iso_offset: <timestamp>

    # Timestamp with offset as an ISO8601 string with `T` replaced by a space.
    iso_offset_space: <timestamp>

    # Timestamp with offset as an ISO8601 string with `:` removed (safe for Windows file systems).
    iso_offset_safe: <timestamp>

  # Details of the last git commit on the repo.
  repo_last_commit:
    # The git commit hash (defaults to `unspecified` if project not under git control).
    hash: <hash>

    # The git commit timestamp as ZonedDateTime (defaults to build timestamp if project not under git control).
    timestamp: <timestamp>

    # The git commit timestamp in different string formats.
    timestamp_formatted:
      # Timestamp in UTC as an ISO8601 string.
      iso_utc: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `T` replaced by a space.
      iso_utc_space: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_utc_safe: <timestamp>

      # Timestamp with offset as an ISO8601 string.
      iso_offset: <timestamp>

      # Timestamp with offset as an ISO8601 string with `T` replaced by a space.
      iso_offset_space: <timestamp>

      # Timestamp with offset as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_offset_safe: <timestamp>

4.2. `vars` - Global variables

User defined variables from global variables YAML file (default: src/variables.yaml).

Any variables defined in that file and placed in a vars top level key and added to the Jinja2 context map.

Important

The YAML file loader by default only allows a maximum of 50 YAML aliases to be used. This is the default setting from snakeyaml (v1.33) designed to protect against the billion laughs attack. If your project contains YAML files with more than 50 aliases, then you can override the max limit in your gradle.properties file via:

// File: gradle.properties

...

// Allow gradle-docs YAML loader to read files with up to 1000 aliases.
com.brightsparklabs.gradle.docs.YAML_MAX_ALIASES = 1000

This setting applies to all YAML files loaded by the system.

The following are added to the Jinja2 context map:

# User defined variables from the global varialbes YAML file (if present).
vars:
  ...

# Details of the last git commit on the global variables YAML file.

vars_file_last_commit:
  # The git commit hash (defaults to `unspecified` if file not under git control).
  hash: <hash>

  # The git commit timestamp as ZonedDateTime (defaults to build timestamp if file not under git control).
  timestamp: <timestamp>

  # The git commit timestamp in different string formats.
  timestamp_formatted:
    # Timestamp in UTC as an ISO8601 string.
    iso_utc: <timestamp>

    # Timestamp in UTC as an ISO8601 string with `T` replaced by a space.
    iso_utc_space: <timestamp>

    # Timestamp in UTC as an ISO8601 string with `:` removed (safe for Windows file systems).
    iso_utc_safe: <timestamp>

    # Timestamp with offset as an ISO8601 string.
    iso_offset: <timestamp>

    # Timestamp with offset as an ISO8601 string with `T` replaced by a space.
    iso_offset_space: <timestamp>

    # Timestamp with offset as an ISO8601 string with `:` removed (safe for Windows file systems).
    iso_offset_safe: <timestamp>

4.3. `template_file` - (Dynamic) Current template file variables

(Dynamic) Variables pertaining to the CURRENT template file being rendered.

template_file:
  # The name of the source template file.
  name: <name>

  # The relative path (in docs directory) of the source template file.
  path: <path>

  # Details of the last git commit on the template file.
  last_commit:
    # The git commit hash (defaults to `unspecified` if file not under git control).
    hash: <hash>

    # The git commit timestamp as ZonedDateTime (defaults to build timestamp if file not under git control).
    timestamp: <timestamp>

    # The git commit timestamp in different string formats.
    timestamp_formatted:
      # Timestamp in UTC as an ISO8601 string.
      iso_utc: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `T` replaced by a space.
      iso_utc_space: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_utc_safe: <timestamp>

      # Timestamp with offset as an ISO8601 string.
      iso_offset: <timestamp>

      # Timestamp with offset as an ISO8601 string with `T` replaced by a space.
      iso_offset_space: <timestamp>

      # Timestamp with offset as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_offset_safe: <timestamp>

  # User defined variables from template specific variables YAML file (if present).
  #
  # A template specific variables file must be named the same as the Jinja2 template file with
  # `.yaml` appended.
  #
  # E.g.
  #
  #   src/docs/introduction.j2      -> Jinja2 template file.
  #   src/docs/introduction.j2.yaml -> Template specific variables YAML file.
  vars:
    ...

  # Details of the last git commit on the template specific variables YAML file (if present).
  vars_file_last_commit:
    # The git commit hash (defaults to `unspecified` if file not under git control).
    hash: <hash>

    # The git commit timestamp as ZonedDateTime (defaults to build timestamp if file not under git control).
    timestamp: <timestamp>

    # The git commit timestamp in different string formats.
    timestamp_formatted:
      # Timestamp in UTC as an ISO8601 string.
      iso_utc: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `T` replaced by a space.
      iso_utc_space: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_utc_safe: <timestamp>

      # Timestamp with offset as an ISO8601 string.
      iso_offset: <timestamp>

      # Timestamp with offset as an ISO8601 string with `T` replaced by a space.
      iso_offset_space: <timestamp>

      # Timestamp with offset as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_offset_safe: <timestamp>

4.4. `template_dir` - (Dynamic) Current template directory variables

(Dynamic) Variables pertaining to the CURRENT directory of the template being rendered.

template_dir:
  # The relative path (in docs directory) of the directory containing the source template file.
  path: <path>

  # User defined variables from directory variables YAML file (`./variables.yaml`).
  vars:
    ...

4.5. `instance_file` - (Dynamic) Current instance file variables

(Dynamic) User defined variables from the CURRENT instance variable file being processed (if present).

# Instance variable files must be stored under a directory with the same name as the Jinja2 template
# file with `.d` appended. Each `.yaml` file under this directory will be rendered against the
# corresponding Jinja2 template file.
#
# E.g.
#
#   src/docs/sops/sop-template.j2                             -> Jinja2 template file.
#   src/docs/sops/sop-template.j2.d/                          -> Instance variables directory.
#   src/docs/sops/sop-template.j2.d/restart-servers.adoc.yaml -> Instance variables file.
#   src/docs/sops/sop-template.j2.d/purge-logs.adoc.yaml      -> Instance variables file.
#
# Will result in the following output directory structure:
#
#   sops/restart-servers.pdf
#   sops/purge-logs.pdf

instance_file:
  # The name of the instance variable YAML file.
  name: <name>

  # The relative path (in docs directory) of the instance variables YAML file.
  path: <path>

  # Details of the last git commit on the instance variables YAML file.
  last_commit:
    # The git commit hash (defaults to `unspecified` if file not under git control).
    hash: <hash>

    # The git commit timestamp as ZonedDateTime (defaults to build timestamp if file not under git control).
    timestamp: <timestamp>

    # The git commit timestamp in different string formats.
    timestamp_formatted:
      # Timestamp in UTC as an ISO8601 string.
      iso_utc: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `T` replaced by a space.
      iso_utc_space: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_utc_safe: <timestamp>

      # Timestamp with offset as an ISO8601 string.
      iso_offset: <timestamp>

      # Timestamp with offset as an ISO8601 string with `T` replaced by a space.
      iso_offset_space: <timestamp>

      # Timestamp with offset as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_offset_safe: <timestamp>

  # Variables from the instance variables file.
  vars:
    ...

4.6. `output_file` - (Dynamic) Current output file variables

(Dynamic) Details of the CURRENT file being rendered.

output_file:
  # The name of the output file.
  name: <name>

  # The relative path (in output directory) of the output file.
  path: <path>

  # Details of the last git commit identified which has had an impact on the content in the
  # generated output file. It is the most LATEST timestamp found amongst:
  #
  # - vars_file_last_commit
  # - template_file.last_commit
  # - instance_file.last_commit
  last_commit:
    # The git commit hash.
    hash: <hash>

    # The git commit timestamp as ZonedDateTime.
    timestamp: <timestamp>

    # The git commit timestamp in different string formats.
    timestamp_formatted:
      # Timestamp in UTC as an ISO8601 string.
      iso_utc: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `T` replaced by a space.
      iso_utc_space: <timestamp>

      # Timestamp in UTC as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_utc_safe: <timestamp>

      # Timestamp with offset as an ISO8601 string.
      iso_offset: <timestamp>

      # Timestamp with offset as an ISO8601 string with `T` replaced by a space.
      iso_offset_space: <timestamp>

      # Timestamp with offset as an ISO8601 string with `:` removed (safe for Windows file systems).
      iso_offset_safe: <timestamp>

4.7. `config` - Plugin configuration variables

The docsPluginConfig object as defined in the Configuration section below.

config:
  ...

4.8. `buildscript_vars` - Buildscript variables

The gradle buildscript can be used to dynamically create files which are added to the Jinja2 context. These generated files need to be placed in the following directory prior to calling the jinjaPreProcess task:

build/brightsparklabs/docs/buildscriptVariables/

The files need to be named analogous to what they are named in the source templates directory, and they will be added to Jinja2 context is the corresponding location under a buildscript_vars key.

The following helpers are exposed under project.ext.bslGradleDocs:

File buildscriptVariablesDir: Returns the buildscript variables directory.
File createBuildscriptVariablesFile(String path): Creates a file at the specified path under the buildscript directory.

Example 5. Using Buildscript variables

Given:

Templates stored in the default location (src/docs).
A global variables file at the default location (src/variables.yaml).

Code in the build.gradle buildscript which has populated:

build/brightsparklabs/docs/buildscriptVariables/

E.g. Via a task:

// build.gradle

import org.yaml.snakeyaml.Yaml

tasks.register('generateVariables') {
    outputs.upToDateWhen { false }

    doLast {
      // ---------------------------------------------------------
      // Example 1: Reshape source variables.
      // ---------------------------------------------------------

      def adminGuideFilePath = 'src/docs/devops/administrator-guide.adoc.j2.yaml'
      def adminGuideFile = project.file(adminGuideFilePath)

      def yamlParser = new Yaml()
      def adminGuideVars = yamlParser.load(adminGuideFile.text)

      // Add an ID to each step.
      adminGuideFile.steps.eachWithIndex { item, index ->
        item.id = "${index + 1}.padLeft(5, '0')
      }

      def buildscriptVarsFile = project.ext.bslGradleDocs.createBuildscriptVariablesFile(adminGuideFilePath)
      buildscriptVarsFile.text = yamlParser.dump(adminGuideVars)

      // ---------------------------------------------------------
      // Example 2: Create global buildscript variables.
      // ---------------------------------------------------------

      def buildscriptGlobalVarsFile =
        project.ext.bslGradleDocs.createBuildscriptVariablesFile('src/variables.yaml')
      buildscriptGlobalVarsFile.text = """
        ---
        foo: 12
        bar: 2
        """.stripIndent().stripLeading()
    }
}
project.tasks.named('jinjaPreProcess'){ dependsOn 'generateVariables' }

The following directory structure:

├── build.gradle
├── src
│   ├── docs
│   │   ├── devops
│   │   │   ├── administrator-guide.adoc.j2
│   │   │   └── administrator-guide.adoc.j2.yaml
│   │   ├── _includes
│   │   │   ├── glossary.adoc.j2
│   │   │   ├── glossary.adoc.j2.yaml
│   │   │   └── variables.yaml
│   │   └── work-packages
│   │       ├── work-package.adoc.j2
│   │       └── work-package.adoc.j2.d
│   │           ├── backend-modernisation.yaml
│   │           └── frontend-modernisation.yaml
│   └── variables.yaml
└── build
    └── brightsparklabs
        └── docs
            └── buildscriptVariables
                └── src
                    ├── docs
                    │   ├── devops
                    │   │   ├── administrator-guide.adoc.j2.yaml
                    │   │   └── variables.yaml
                    │   └── work-packages
                    │       ├── work-package.adoc.j2.yaml
                    │       └── work-package.adoc.j2.d
                    │           └── backend-modernisation.yaml
                    └── variables.yaml

The following would be available in the context map for the specified template:

administrator-guide.adoc.j2

...

# Populated from: `src/variables.yaml`
vars:
  ...

# Populated from: `build/brightsparklabs/docs/buildscriptVariables/src/variables.yaml`
buildscript_vars:
  ...

template_file:
  ...

  # Populated from: `src/docs/devops/administrator-guide.adoc.j2.yaml`
  vars:
    ...

  # Populated from: `.../buildscriptVariables/src/docs/devops/administrator-guide.adoc.j2.yaml`
  buildscript_vars:
    ...

template_dir:
  ...

  # Populated from: `.../buildscriptVariables/src/docs/devops/variables.yaml`
  buildscript_vars:
    ...

glossary.adoc.j2

...

# Populated from: `src/variables.yaml`
vars:
  ...

# Populated from: `build/brightsparklabs/docs/buildscriptVariables/src/variables.yaml`
buildscript_vars:
  ...

template_file:
  ...

  # Populated from: `src/docs/_includes/glossary.adoc.j2.yaml`
  vars:
    ...

template_dir:
  ...

  # Populated from: `src/docs/_includes/variables.yaml`
  vars:
    ...

backend-modernisation.adoc (rendered from work-package.adoc.j2)

...

# Populated from: `src/variables.yaml`
vars:
  ...

# Populated from: `build/brightsparklabs/docs/buildscriptVariables/src/variables.yaml`
buildscript_vars:
  ...

instance_file:
  ...

  # Populated from: `src/docs/work-packages/work-package.adoc.j2.d/backend-modernisation.yaml`
  vars:
    ...

  # Populated from: `.../buildscriptVariables/src/docs/work-packages/work-package.adoc.j2.d/backend-modernisation.yaml`
  buildscript_vars:
    ...

template_file:
  ...

  # Populated from: `.../buildscriptVariables/src/docs/work-packages/work-package.adoc.j2.yaml`
  buildscript_vars:
    ...

frontend-modernisation.adoc (rendered from work-package.adoc.j2)

...

# Populated from: `src/variables.yaml`
vars:
  ...

# Populated from: `build/brightsparklabs/docs/buildscriptVariables/src/variables.yaml`
buildscript_vars:
  ...

instance_file:
  ...

  # Populated from: `src/docs/work-packages/work-package.adoc.j2.d/frontend-modernisation.yaml`
  vars:
    ...

template_file:
  ...

  # Populated from: `.../buildscriptVariables/src/docs/work-packages/work-package.adoc.j2.yaml`
  buildscript_vars:
    ...

5. Tasks

The plugin adds the following gradle tasks:

5.1. jinjaPreProcess

Performs Jinja2 pre-processing on documents.

5.2. asciidoctor

Generic task to convert AsciiDoc files and copy related resources.

This will automatically be added as a dependency to the build task.

Alias bslAsciidoctor.

5.3. asciidoctorPdf

Convert AsciiDoc files to PDF format.

Alias bslAsciidoctorPdf.

6. Configuration

Use the following configuration block to configure the plugin:

// file: build.gradle

project.version = 'git describe --always --dirty'.execute().text.trim()

docsPluginConfig {
    // Set to `true` to auto import brightSPARK Labs Jinja2 macros under `brightsparklabs`
    // namespace. Default: `true`.
    autoImportMacros = false

    // Path to a header file (relative to project root) which contains a header to prepend to each
    // Jinja2 file prior to rendering. Default: `src/header.j2`.
    templateHeaderFile = 'src/my-custom-header.j2'

    // Path to a footer file (relative to project root) which contains a footer to append to each
    // Jinja2 file prior to rendering. Default: `src/footer.j2`.
    templateFooterFile = 'src/my-custom-footer.j2'

    // YAML file containing context variables used when rendering Jinja2 templates.
    // Default: `src/variables.yaml`.
    variablesFile = 'src/my-variables.yaml'

    // Name of the directory (relative to project root) containing the documents to process.
    // Default: `src/docs/`.
    docsDir = 'asciiDocs/'

    // Name of the directory (relative to project root) containing the source images.
    // Default: `src/images`.
    sourceImagesDir = 'images/'

    // Name of the directory (relative to project root) where the images are copied for processing.
    // Default: `build/docs/images/`.
    buildImagesDir = 'build/images/'

    // Position for the Table of Contents. Refer to:
    //  - https://docs.asciidoctor.org/asciidoc/latest/toc/position
    // Default: `left`.
    tocPosition = 'macro'

    // Classification to add to the document header/footer.
    // Default: `OFFICIAL`.
    classification = ''

    // Theme to apply to PDF. Defaults to the brightSPARK Labs theme.
    // Default: brightSPARK Labs in-built theme.
    //
    // To use a custom theme, ensure you have first configured the `pdfThemes` extension object
    // from the AsciidoctorPdf plugin
    // (https://asciidoctor.github.io/asciidoctor-gradle-plugin/master/user-guide/#asciidoctorj-pdf-plugin),
    // then set this option to the name of the theme.
    //
    // E.g.
    //
    //   pdfThemes {
    //       github 'basic', {
    //           organisation = 'fwilhe2'
    //           repository = 'corporate-theme'
    //           relativePath = 'resources/themes'
    //           branch = 'master'
    //       }
    //   }
    theme = 'basic'

    // Modifications that will be made to the default asciidoctorj options for rendering the document.
    // Adding a non-existent key will add the option.
    // Adding an existing key will override the pre-existing option.
    // Adding an existing key with a value of `null` will remove the option.
    // Default: `["doctype@" : 'book']`
    options = ["doctype@" : 'article']

    // Modifications that will be made to the list of attributes that will be used by asciidoctor when rendering the documents.
    // Adding a non-existent key will add the attribute.
    // Adding an existing key will override the pre-existing attribute.
    // Adding an existing key with a value of `null` will remove the attribute.
    // Default: `[
    //           // Asciidoctor attributes.
    //           'doctype@'           : 'book',
    //           '!chapter-signifier' : '',
    //           'icon-set@'          : 'fas',
    //           'icons@'             : 'font',
    //           'imagesdir@'         : project.file(config.buildImagesDir),
    //           'sectnums@'          : '',
    //           'sectnumlevels@'     : '5',
    //           'source-highlighter@': 'coderay',
    //           'toc@'               : config.tocPosition,
    //           'pdf-theme@'         : config.theme.orElse('brightspark-labs'),
    //
    //           // BSL attributes.
    //           'bsl_classification@'       : config.classification,
    //           'bsl_project_name@'         : global_context.sys.project_name,
    //           'bsl_project_description@'  : global_context.sys.project_description,
    //           'bsl_project_version@'      : global_context.sys.project_version,
    //           'bsl_repo_last_commit_hash@': global_context.sys.repo_last_commit.hash,
    //           ]`.
    attributes = [
        // Use `article` style by default rather than `book`.
        'doctype@': 'article',
        // Clear the table of contents setting.
        'toc@'    : null
    ]

   // --------------------------------------------------------------------------
   // Configuration for website generation.
   // --------------------------------------------------------------------------

   // NOTE: Website generation only available when `docker buildx` is present on system.

   // Title to display in the website. Default: `Documentation`.
   website.title = 'My Documentation'

   // Email to use in the website. Default: `enquire@brightsparklabs.com`.
   website.email = 'email@me.dev'

   // Description to display in the website. Default: The gradle project description.
   website.description = 'Documentation explaining how Project X operates.'

   // The subpath of the site if required. Default: ``.
   website.baseurl = '/projectX/documentation'

   // Domain portion of the site if required. DO NOT include trailing slashes. Default: ``.
   website.url = 'http://projectX.com'

   // Gem-based Jekyll theme to use when styling the website.
   // See https://jekyllrb.com/docs/themes/#understanding-gem-based-themes.
   // Default: `just-the-docs`.
   website.theme = 'minimal-mistakes-jekyll'
}

6.1. Filtering output

Generating PDF files can be time intensive. If you only want to generate specific files, you can specify which files to generate using a Gradle property.

Example 6. Filtering output

Given this src directory setup:

src
└── docs
    ├── intro
    │   ├── introduction.adoc.j2
    │   ├── introduction.adoc.j2.yaml
    │   ├── overview.adoc.j2
    │   └── overview.adoc.j2.yaml
    └── outro
        ├── conclusion.adoc.j2
        ├── conclusion.adoc.j2.yaml
        ├── overview.adoc.j2
        └── overview.adoc.j2.yaml

If the property is set as follows:

./gradlew  -PbslDocsInclude=src/docs/intro,src/docs/outro/conclusion.adoc

Then the resulting Jinja2 output directory would contain:

jinjaProcessed
├── intro
│   ├── introduction.adoc
│   └── overview.adoc
└── outro
    └── conclusion.adoc

6.2. brightSPARK Labs Jinja2 Macros

If the configuration field autoImportMacros is set to true (default) then the following macros shall be be available under the brightsparklabs namespace:

add_default_attributes() - Adds the standard set of AsciiDoc attributes to the document.

These can be used as follows:

{{ brightsparklabs.add_default_attributes() }}

Macros are defined in:

src/main/resources/brightsparklabs-macros.j2

6.3. Asciidoctorj Diagram

asciidoctorj-diagram is automatically enabled.

In order to make use of the various diagramming formats, the backing tool needs to be installed on the system.

The CLI tools listed below are installed in the containers used by the asciidoctorPdfDocker and generateJekyllWebsite tasks. I.e. These tasks can be used to create documents containing diagrams of the listed types without needing to install those tools on the local workstation.

graphviz dot

Allowing the use of graphviz/plantuml diagrams.

  Generate PNG file (with random name) from graphviz spec.

  [graphviz]
  ....
  digraph G {
      main -> parse -> execute;
      main -> init;
      main -> cleanup;
      execute -> make_string;
      execute -> printf
      init -> make_string;
      main -> printf;
      execute -> compare;
  }
  ....

  Generate `my-diagram.svg` from plantuml spec.

  [plantuml,my-diagram,svg]
  ....
  @startjson
  {
     "fruit":"Apple",
     "size":"Large",
     "color": ["Red", "Green"]
  }
  @endjson
  ....

vega-cli

Allowing the use of Vega/Vega-Lite diagrams.

  [vega,bar-chart,svg]
  ....
  {
    "description": "A simple bar chart with embedded data.",
    "data": {
      "values": [
        {"a": "A","b": 28}, {"a": "B","b": 55}, {"a": "C","b": 43},
        {"a": "D","b": 91}, {"a": "E","b": 81}, {"a": "F","b": 53},
        {"a": "G","b": 19}, {"a": "H","b": 87}, {"a": "I","b": 52}
      ]
    },
    "mark": "bar",
    "encoding": {
      "x": {"field": "a", "type": "ordinal"},
      "y": {"field": "b", "type": "quantitative"}
    }
  }
  ....

7. Jekyll Website

By default the generated Jekyll website uses the Just the Docs theme.

By default all pages will appear as top level pages in the main navigation. If you want to setup nested navigation, you will need to set that up explicitly as detailed in the Navigation Structure documentation.

Example 7. Nested navigation

$ tree

src
└── docs
    ├── data-model
    │   ├── component-x-data-model.adoc.j2
    │   ├── component-x-data-model.adoc.j2.yaml
    │   └── index.adoc.j2
    └── index.adoc.j2

$ cat src/docs/index.adoc.j2
 Data Model
brightSPARK Labs <enquire@brightsparklabs.com>
{{ brightsparklabs.add_default_attributes() }}
:page-has_children: true

$ head src/docs/component-x-data-model.adoc.j2
 Component X Data Model
brightSPARK Labs <enquire@brightsparklabs.com>
{{ brightsparklabs.add_default_attributes() }}
:page-parent: Data Model

The attributes to note:

:page-has_children: true on the parent page to indicate supports nested pages.
:page-parent: Data Model on the child page to nest it under the parent page.

NOTE: Just the Docs only supports a maximum of 3 levels of nesting.

7.1. Website Dockerfile

A Dockerfile for building the website can be generated via the generateDockerfile task. This can be leveraged to work with the gradle-docker plugin by doing the following:

Make the gradle-docker plugin’s buildDockerImages task depend on this plugin’s generateDockerfile task.
Add the path of the generated Dockerfile to the gradle-docker plugin’s configuration block in the dockerFileDefinitions list.

8. Testing during development

To test plugin changes during development:

# ------------------------------------------------------------
# Create a test application.
# ------------------------------------------------------------

mkdir gradle-docs-test
cd gradle-docs-test
gradle init --type java-application --dsl groovy

# ------------------------------------------------------------
# Add the plugin (NOTE: do not specify a version).
# ------------------------------------------------------------

sed -i "/plugins/ a id 'com.brightsparklabs.gradle.docs'" build.gradle

# ------------------------------------------------------------
# Setup git (plugin requires repo to be under git control).
# ------------------------------------------------------------

git init
git add .
git commit "Initial commit"
git tag -a -m "Tag v0.0.0" 0.0.0

# ------------------------------------------------------------
# Run using the development version of the plugin.
# ------------------------------------------------------------

gradlew --include-build /path/to/gradle-docs <task>

9. Licenses

Refer to the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 341 Commits
.github		.github
gradle/wrapper		gradle/wrapper
src/main		src/main
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.adoc		README.adoc
build.gradle		build.gradle
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

gradle-docs

1. Compatibility

2. Build

2.1. Publishing

3. Usage

3.1. Tasks

4. Jinja2 Context Map

4.1. `sys` - System variables

4.2. `vars` - Global variables

4.3. `template_file` - (Dynamic) Current template file variables

4.4. `template_dir` - (Dynamic) Current template directory variables

4.5. `instance_file` - (Dynamic) Current instance file variables

4.6. `output_file` - (Dynamic) Current output file variables

4.7. `config` - Plugin configuration variables

4.8. `buildscript_vars` - Buildscript variables

5. Tasks

5.1. jinjaPreProcess

5.2. asciidoctor

5.3. asciidoctorPdf

6. Configuration

6.1. Filtering output

6.2. brightSPARK Labs Jinja2 Macros

6.3. Asciidoctorj Diagram

7. Jekyll Website

7.1. Website Dockerfile

8. Testing during development

9. Licenses

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

gradle-docs

1. Compatibility

2. Build

2.1. Publishing

3. Usage

3.1. Tasks

4. Jinja2 Context Map

4.1. sys - System variables

4.2. vars - Global variables

4.3. template_file - (Dynamic) Current template file variables

4.4. template_dir - (Dynamic) Current template directory variables

4.5. instance_file - (Dynamic) Current instance file variables

4.6. output_file - (Dynamic) Current output file variables

4.7. config - Plugin configuration variables

4.8. buildscript_vars - Buildscript variables

5. Tasks

5.1. jinjaPreProcess

5.2. asciidoctor

5.3. asciidoctorPdf

6. Configuration

6.1. Filtering output

6.2. brightSPARK Labs Jinja2 Macros

6.3. Asciidoctorj Diagram

7. Jekyll Website

7.1. Website Dockerfile

8. Testing during development

9. Licenses

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

4.1. `sys` - System variables

4.2. `vars` - Global variables

4.3. `template_file` - (Dynamic) Current template file variables

4.4. `template_dir` - (Dynamic) Current template directory variables

4.5. `instance_file` - (Dynamic) Current instance file variables

4.6. `output_file` - (Dynamic) Current output file variables

4.7. `config` - Plugin configuration variables

4.8. `buildscript_vars` - Buildscript variables

Packages