documentation_builder library

Classes

AllGitHubBadges
A ExpressionFunction that creates markdown for all github.com badges.
AllPubBadges
A ExpressionFunction that creates markdown for all pub.flutter-io.cn badges.
AllPubGitHubBadges
A ExpressionFunction that creates markdown for all pub.flutter-io.cn and github.com badges.
Badge
Badges are images with text that inform the user on the technology used in a project and other relevant information such as links to
BadgeFunctions
Bsd3License
A concrete implementation of a license text for the BSD 3-Clause License
BuildCommand
Builds the documentation files from template files by starting build_runner build.
BuilderVariable
BuildOptionParameter<T>
BuildStepFileTemplate
BuildStepVariable
Helper class
CliTemplateEngine
A template engine for the CLI that uses the documentation_builder functions. It uses the [[ and ]] tags to delimit template expressions to differentiate from the {{ and }} tags is used in DocumentationTemplateEngine.
ColorParameter
A ExpressionFunction-Parameter for the Badge color.
Command
CommandLineFailure
CommandLineResult
Represents the result of Commands.find.
CommandLineSuccess
Commands
CustomBadge
A ExpressionFunction that creates a customizable badge image in markdown format.
DartCodePathParameter
An ExpressionFunction-Parameter for a Dart code path.
DartDocCommentParser
DartDocCommentParser parses dart documentation comments:
DartMemberPath
A DartMemberPath is a dot separated path to a member inside the Dart file. It is a part of a SourcePath.
DocumentationBuilder
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.
DocumentationTemplateEngine
The DocumentationBuilder uses the DocumentationTemplateEngine to parse the templates and later to render the parseResult.
EndOfInputOrPreviousFailureParser
A parser that succeeds at the end of input. OR results with an failure with the message of the owning parser Inspired by EndOfInputParser
FileHeaderMap
FileHeaders
  • Description: A map of file suffixes and the file header template to be added (which can be null)
  • Default value: 
    {
'LICENSE': null,
'LICENSE.md': null,
'.md':
    '[//]: # (This file was generated from: {{inputPath()}} using the documentation_builder package)&#92;n&#92;r',
'.dart':
    '/// This file was generated from: {{inputPath()}} using the documentation_builder package&#92;n&#92;r'
}
    • GeneratorFunctions
    / A group of functions related to generator functions that create (markdown) text
    GitHubBadge
    A ExpressionFunction that creates markdown for a badge of a project on github.com.
    GitHubIssuesBadge
    A ExpressionFunction that creates markdown for a badge with the amount of open issues on github.com.
    A LinkFunction that creates a markdown hyperlink to a GitHub issues page.
    GitHubLicenseBadge
    A ExpressionFunction that creates markdown for a badge with the project license on github.com.
    A LinkFunction that creates a markdown hyperlink to a GitHub project page.
    GitHubMileStones
    A function that generates a markdown text of GitHub milestones
    A LinkFunction that creates a markdown hyperlink to a GitHub milestones page.
    GitHubProject
    Provides project information if the projects is stored on https://github.com
    GitHubPullRequestsBadge
    A ExpressionFunction that creates markdown for a badge with the amount of open pull requests on github.com.
    A LinkFunction that creates a markdown hyperlink to a GitHub pull requests page.
    Gets a uri to plain view of the source file. e.g. if you open the uri and click on a markdown file in github, it will show the rendered markdown file You can use this link instead to see the un-rendered (source) file.
    A LinkFunction that creates a markdown hyperlink to a GitHub releases page.
    GitHubStarsBadge
    A ExpressionFunction that creates markdown for a badge with the amount of stars on github.com.
    A LinkFunction that creates a markdown hyperlink to a GitHub wiki page.
    GitHubWikiBadge
    A ExpressionFunction that creates markdown for a badge of the Wiki pages of a project on github.com.
    A LinkFunction that creates a markdown hyperlink to a GitHub wiki page.
    HelpCommand
    A command that shows the available commands.
    ImportCode
    Imports a file (e.g. html, json, or any other programming related file) from this projects and puts it in a Markdown code block.
    ImportDartCode
    Reads the source file from the given path and puts it in a Markdown code block.
    ImportDartDoc
    Imports Dart documentation comments for a given library member from a dart code file And converts them to a Markdown
    InputPath
  • Description: An expression where to find template files
  • Default value: 'doc/template/{{filePath}}.template'
    • InputPathFunction
    Returns the path of the template file being used.
    LabelParameter
    A ExpressionFunction-Parameter for the Badge label.
    LibraryCacheVariable
    License
    A function that generates a license text for a given type, year and copyright holder
    Licenses
    A collection of licenses that can be used to generate license texts
    LicenseText
    An abstract class that defines the structure for license texts
    LicenseTypeParameter
    A ExpressionFunction-Parameter for the Badge license type.
    LinkFunction
    An ExpressionFunction that creates a markdown hyperlink This class ensures a convention is followed so that implementations can be reused in PathFunctions
    LinkFunctions
    A group ExpressionFunctions that create markdown hyperlinks.
    LinkParameter
    A ExpressionFunction-Parameter for the Badge link.
    LocalProject
    Provides information on the local project such as:
    Represents a Markdown hyperlink with text and a URI.
    MarkDownLinkFactories
    A collection of Markdown link factories that can create MarkDownLinks for different reference types.
    MarkDownLinkFactory
    Factory interface for creating Markdown links from references.
    MergedImportFunctions
    Functions from the template_engine package and this package in an order that makes most sense for documentation_builder
    MergedPathFunctions
    Functions from the template_engine package and this package in an order that makes most sense for documentation_builder
    MessageParameter
    A ExpressionFunction-Parameter for the Badge message.
    MitLicense
    A concrete implementation of a license text for the MIT License
    OutputPath
  • Description: An expression where to store the result files
  • Default value: '{{filePath}}'
    • OutputPathFunction
    Returns the path of the file being created from the template.
    ProjectFilePath2
    Alternative ProjectFilePath2 other than template_engine package, because we need to do without endWithBetterFailure() for SourcePath;
    A LinkFunction that creates a markdown hyperlink to the change log page of a pub.flutter-io.cn package.
    A LinkFunction that creates a markdown hyperlink to the example page of a pub.flutter-io.cn package.
    A LinkFunction that creates a markdown hyperlink to the install page of a pub.flutter-io.cn package.
    A LinkFunction that creates a markdown hyperlink to the license page of a pub.flutter-io.cn package.
    A LinkFunction that creates a markdown hyperlink to a pub.flutter-io.cn package.
    PubDevPackageLinkFactory
    Creates a MarkDownLink for a package on pub.flutter-io.cn.
    PubDevProject
    Provides project information on a project on https://github.com
    A LinkFunction that creates a markdown hyperlink to the score page of a pub.flutter-io.cn package.
    A LinkFunction that creates a markdown hyperlink to the versions page of a pub.flutter-io.cn package.
    PubPackageBadge
    A ExpressionFunction that creates markdown for a badge of an existing Dart or Flutter package on pub.flutter-io.cn.
    PubScoreBadge
    A ExpressionFunction that creates markdown for a badge of the scores on pub.flutter-io.cn.
    ReferenceConverter
    Dart Documentation Comments can contain references. See https://dart.cn/tools/doc-comments/references We try to replace them with a markdown link
    A ExpressionFunction that creates a markdown hyperlink to a reference. The reference can be a URL, a package name on pub.flutter-io.cn, a source file, or a Dart library member.
    RenderFunction
    SetupCommand
    Sets up a project to use the documentation_builder package.
    SetupTemplate
    A Template for setting up the project with the documentation_builder CLI. This template is used to create the necessary files and configurations The Template is processed by the SetupCommand:
    SourceLinkFactory
    Creates a MarkDownLink to a Dart source file or one of its members on github.com
    SourcePath
    A SourcePath is a reference to a piece of your Dart source code. This could be anything from a whole dart file to one of its members. Format: <ProjectFilePath2>#<DartMemberPath>
    SuffixParameter
    A ExpressionFunction-Parameter that represents a suffix to append to the URI.
    TableOfContents
    A function that generates a markdown table of contents for a template file or folder
    TableOfContentsDummy
    dummy function to prevent round trips.
    TableOfContentsFactory
    TextParameter
    A ExpressionFunction-Parameter that represents the text of a hyperlink.
    Represents a Markdown hyperlink to a title in some Markdown file.
    ToolTipParameter
    A ExpressionFunction-Parameter for the Badge toolTip.
    UriFunction
    This class is used to create a ExpressionFunctions that return a Uri by copying LinkFunctions.
    UrlMarkDownLinkFactory
    Creates a MarkDownLink for a URL reference.

    Extensions

    EndOrPreviousFailureExtension on Parser<R>
    UriExtension on Uri
    / Extension methods for Uri to append path, query parameters, and fragment. This allows for more flexible URI manipulation without creating a new Uri object each time.

    Constants

    newLine → const String
    Characters for a new line We are using what Linux and thus Git seems to prefer: Carriage Return (\r) Line Feed ($newLine)

    Properties

    gitHubProjectResource → Resource<GitHubProject>
    final
    libraryCacheResource → Resource<LibraryCache>
    final
    pubDevProjectResource → Resource<PubDevProject>
    final

    Functions

    addDevDependency(String package) → Future<void>
    Adds a package as a dev dependency using 'dart pub add'.
    createDocumentationFunctionGroups() → List<FunctionGroup>
    merges FunctionGroups that come pre-packaged as part of the template_engine package with additional FunctionGroups specific for documentation_builder where the most important documentation_builder FunctionGroups are ordered first.
    createDocumentationTemplates(GitHubProject gitHubProject) → Future<List<SetupTemplate>>
    createGitHubWorkflowTemplates(GitHubProject gitHubProject) → Future<List<SetupTemplate>>
    deepMerge(Map<String, dynamic> base, Map<String, dynamic> update) → Map<String, dynamic>
    findAllCliTemplatesFromGitHub(GitHubProject gitHubProject, String path) → Future<List<SetupTemplate>>
    findElementRecursively(Element element, DartMemberPath path) → Element?
    Finds a Dart member element by its path in the given element so we do not need a visitor.
    hasDependency(YamlMagic yaml, String package) → bool
    markdownTitleParser() → Parser<({String hashes, String title})>
    mergeDocumentationBuilderBuildYaml(YamlMagic source) → YamlMagic
    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):
    normalizeNewLines(String text) → String
    converts all Line Feeds ($newLine) to Carriage Return (\r) Line Feed ($newLine)
    normalizePathSeparators(String path, String pathSeparator) → String
    parseYaml({required String yamlString, required String sourcePath}) → YamlMagic
    resolveLibrary(RenderContext context, ProjectFilePath2 dartFile) → Future<LibraryElement>
    Resolves the LibraryElement for the given dartFile.
    validateIfMemberFound(Element? foundElement, SourcePath path) → void
    yamlDeepMerge(YamlMagic source, YamlMagic toAdd) → YamlMagic

    Typedefs

    CliTemplateFile = ({File input, File output})
    LibraryCache = Map<ProjectFilePath2, LibraryElement>
    gets a Map where key = ProjectFilePath and value = a LibraryElement which is parser tree from the dart source code file. We cache these because creating them (parsing) takes time.

    Exceptions / Errors

    BuildOptionParameterException