To use this plugin:
- add the plugin to
addSbtPlugin("dev.atedeg" % "sbt-ubiquitous-scaladoc" % "latest-version")
- specify in the
build.sbtfile the folder where to get the html files to parse and the folder where to put the generated markdown files:
ThisBuild / ubidoc / targetDirectory := "myTargetDir" ThisBuild / ubidoc / lookupDirectory := "myHtmlDir"
The lookupDirectory must contain the
scripts/searchData.js file generated by
You can instruct the plugin on how to build the markdown tables via a
.ubidoc.yml) configuration file that must be in the project's root. The file must have the following structure:
tables: <list of table objects> ignored: <list of specifiers>
table object has the following structure:
name: "the table's name" termName: "the name used for the term column, if not specified defaults to 'Term'" definitionName: "the name used for the definition column, if not specified defaults to 'Definition'" rows: <list of specifier>
specifier is used to denote an entity of the domain, when adding a specifier to the rows of a table its
name will be included in the table's term column and its documentation will be included in the definition's column.
Currently the supported specifiers cover most of Scala's structures:
//A list of all possible specifiers: - class: "ClassName" - enum: "EnumName" - case: "CaseName" - trait: "TraitName" - type: "TypeName" - def: "DefName"
How the plugin works
For each specifier in the table's rows the plugin looks at its documentation (scraped from the files generated by
and adds a row in the generated markdown table. The name of the entity is normalized by splitting it on uppercase letters so that it is no longer
in camel case.
If, by the end of the process that generates all tables there are leftover entities that were neither in any table nor in the ignored list
the plugin issues a warning listing all those entities. This is used as a sanity check since one may forget to include an important domain
concept. To avoid having any warning one must explicitly specify which entities have to be ignored by adding their specifiers to the
Head to mdm to see a working example of the plugin.