-
-
Notifications
You must be signed in to change notification settings - Fork 151
README generation and repo specific package metadata
Work is underway adding various pieces of metadata to all packages to provide better (and more unified) documentation and facilitate related infrastructure. Currently, this metadata is only used for the generation of README.md files for each package in the repo, however, I imagine these data points also feeding into other documentation efforts in the future.
The script generating the new readme files is located here: /tools/src/readme.ts.
The script uses a package's tpl.readme.md template file and the following data fields in package.json.
Note for contributors: Please only ever edit the tpl.readme.md files, since README.md files will be generated from those templates.
Full package name
brief package overview
Formatted as a list of links to dependencies
An object of project-specific metadata with the following keys (all are optional, as is the presence of the object itself):
An array of { title: string, url: string } objects to related blog posts
Name of the (feature) branch to use in links. Mainly intended for upcoming/WIP packages.
Fully qualified name of parent package (only used in support packages).
Array of short package names related (but not a dependency) to this package.
A string indicating general development status, one of:
-
"alpha"- bleeding edge / work-in-progress -
"beta"- possibly breaking changes forthcoming -
"stable"- used in production -
"refactor"- undergoing major refactoring
Year the project was started (for copyright message)
The thi.ng object can also be used in example projects (under /examples) and uses these relevant fields:
A boolean (default: false) or an array of short package names (i.e. without the @thi.ng/ scope prefix). The example will only be included in the readme file if the value is true or the package name for which the readme is being generated is in the list.
An image path to a screenshot (or another related image), relative to the repo's /assets directory.
Unique function reference names referring to TSDoc refs in the API JSON reports generated by API extractor. The switch to this new doc system and the refactoring/updating of doc strings in all packages is ongoing separately on the feature/api-extractor branch, and once ready, will hopefully provide some easy ways to inject a selection of curated API docs into the readme... A test repo with the generated results is here:
https://github.com/thi-ng/umbrella-docs-temp/blob/master/index.md
The api metadata field would be an array of TSDoc refs to include docs for and would then be looked up from the .ae/<packagename>.api.json reports.
The readme.ts script also uses AUTHORS.md files to inject contributor details into the readme.