documentation_builder 2.0.1

Generates documentation files that can import other files or Dart documentation comments.

documentation_builder

Generates documentation files from template files. This can be useful when you write documentation for a Dart or Flutter project and want to reuse/import files or Dart documentation comments.

It can generate any type of text file e.g.:

• README.md
• LICENSE
• CHANGELOG.md
• Example files
• GitHub wiki files
• or any other text file

documentation_builder is not intended to generate API documentation. Use dartdoc instead.

Features

documentation_builder uses the template_engine package with additional functions for documentation. The most commonly used functions for documentation are:

• Import Functions
• Generator Functions
• Path Functions
• Link Functions
• Badge Functions

Examples

The documentation_builder's own documentation was generated by itself and serves as a showcase.

You can view the templates files and the generated output on https://github.com and https://pub.dev:

README.md

• Template example
• Generated example
• Rendered example

LICENSE

• Template example
• Generated example

CHANGELOG.md

• Template example
• Generated example
• Rendered example

example.md

• Template example
• Generated example
• Rendered example

Wiki pages

• Template examples (click on the raw button to see the generated markdown)
• Rendered examples

Getting Started

The easy way

The simplest way to use the documentation_builder package is to use it as a command line tool.

To install it, run dart pub global activate documentation_builder from the command line.

After installation you can use the following commands:

• documentation_builder help Shows available commands.
• documentation_builder setup Sets up a project to use the documentation_builder:
  • Adds build_runner as dev dependency if needed
  • Adds documentation_builder as dev dependency if needed
  • Adds or updates build.yaml
  • Adds template files if needed
  • Adds github publish-wiki workflow if needed
• documentation_builder build Generates documentation files from template files by starting build_runner build.

The hard way: step by step

• Read the Wiki documentation
• Install documentation_builder developer dependencies in in your project:

  dart pub add --dev build_runner
  dart pub add --dev documentation_builder
  

  build_runner is a tool to run file generators like documentation_builder
• Configure the documentation_builder Add a build.yaml file to the root of your project with the following lines (or merge lines if build.yaml file already exists):

  targets:
    $default:
      sources:
      - doc/**
      - lib/**
      - bin/**
      - web/**
      - test/**
      - pubspec.*
      - $package$
      builders:
        documentation_builder|documentation_builder:
          enabled: True
          # options:
            # input_path:
              # An expression where to find template files
              # Defaults to 'doc/template/{{filePath}}.template'
            # output_path:
              # An expression where to store the result files
              # Defaults to '{{filePath}}'
            # file_headers:
              # A map of file output suffixes and the file header template to be added (which can be null), defaults to:
           # LICENSE: null
           # LICENSE.md: null
           # .md: '[//](https://pub.dev/packages///): "# (This file was generated from: {{inputPath()}} using the documentation_builder package)"
           # .dart: "// This file was generated from: {{inputPath()}} using the documentation_builder package"
  

  For more information on the build.yaml file see build_config
• Create 'doc/template' folders in the root of your project
• Create template files in the "doc/template" folder. See examples
• Generate the documentation files
• Publish the documentation files