01 Documentation Builder - domain-centric/documentation_builder GitHub Wiki

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.:

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:

Breaking Changes

documentation_builder 1.0.0 has had major improvements over earlier versions:

This resulted in the following breaking changes:

  • Tags

    old syntax new syntax
    {ImportFile file:'OtherTemplateFile.md.template' title='# Other Template File'} # Other Template File{{importTemplate('OtherTemplateFile.md.template')}}
    {ImportCode file:'file_to_import.txt' title='# Code example'} # Code example{{importCode('file_to_import.txt')}}
    {ImportDartCode file:'file_to_import.dart' title='# Dart code example'} # Dart code example{{importDartCode('file_to_import.dart')}}
    {ImportDartDoc path='lib\my_lib.dart|MyClass' title='# My Class'} # My Class{{importDartDoc('lib\my_lib.dart|MyClass')}}
    {TableOfContents title='# Table of contents example'} # Table of contents{{tableOfContents(path='doc/template/doc/wiki')}}
    {MitLicense name='John Doe'} {{license(type='MIT', name='John Doe')}}

    See the function documentation for more details on these and new functions

  • Links

    old syntax new syntax
    [GitHub] {{gitHubLink()}}
    [GitHubWiki] {{gitHubWikiLink()}}
    [GitHubStars] {{gitHubStarsLink()}}
    [GitHubIssues] {{gitHubIssuesLink()}}
    [GitHubMilestones] {{gitHubMilestonesLink()}}
    [GitHubReleases] {{gitHubReleasesLink()}}
    [GitHubPullRequests] {{gitHubPullRequestsLink()}}
    [GitHubRaw] {{referenceLink('ref')}} or{{gitHubRawLink()}}
    [PubDev] {{pubDevLink()}}
    [PubDevChangeLog] {{pubDevChangeLogLink()}}
    [PubDevVersions] {{pubDevVersionsLink()}}
    [PubDevExample] {{pubDevExampleLink()}}
    [PubDevInstall] {{pubDevInstallLink()}}
    [PubDevScore] {{pubDevScoreLink()}}
    [PubDevLicense] {{pubDevLicenseLink()}}
    PubDev package links {{referenceLink()}}
    Dart code links {{referenceLink('ref')}}
    Markdown file links [title](URI)

    See the function documentation for more details on these and new functions

  • Badges

    old syntax new syntax
    [CustomBadge title='title' ...] [title]({{customBadge()}})
    [PubPackageBadge title='title'] [title]({{pubPackageBadge()}})
    [GitHubBadge title='title'] [title]({{gitHubBadge()}})
    [GitHubWikiBadge title='title'] [title]({{gitHubWikiBadge()}})
    [GitHubStarsBadge title='title'] [title]({{gitHubStarsBadge()}})
    [GitHubIssuesBadge title='title'] [title]({{gitHubIssuesBadge()}})
    [GitHubPullRequestsBadge title='title'] [title]({{gitHubPullRequestsBadge()}})
    [GitHubLicenseBadge title='title'] [title]({{gitHubLicenseBadge()}})

    See the function documentation for more details on these and new functions

  • Github-Wiki pages are now generated somewhere in the project folder (e.g. doc\wiki) and need to be copied to GitHub. This could be done using GitHub actions (e.g. after each commit). For more information see Automatically Publishing Wiki pages