-
-
Notifications
You must be signed in to change notification settings - Fork 169
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: scripts/generate-readme. It's not deployed yet but will be used starting with the next release cycle...
The script uses a package's README.tpl.md file and the following data fields in package.json.
Note for contributors: In the future, please only edit the README.tpl.md files, since README.md files will be generated from those templates. At the time of writing this most of the templates are still blank and first need to be populated with (some of the) existing content.
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.
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 begun (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 generate-readme script also uses AUTHORS.md files to inject contributor details into the readme.