Feature: Doc template generator · Issue #31 · getsynth/synth · GitHub
source link: https://github.com/getsynth/synth/issues/31
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Required Functionality
We feel that for now, synth namespaces are not currently well documented. Some markdown (or similar format) describing the meaning of columns, etc. would really go a long way to make the definitions more approachable.
Proposed Solution
To reduce the work to set up such documentation and induce a certain consistency, a synth doc subcommand could parse the schema and issue a README.md in the namespace that can then be extended to create some usable documentation.
The template should have the following sections:
- A short description (obviously left as an exercise to the author)
- The collections of the namespace with
- field names, types and descriptions (the latter also to be added by the author)
- dependencies to other collections (e.g. foreign keys, subcollections)
- A minimal pretty-printed (perhaps abridged if too long) generated output of the namespace.
Use case
The documentation would help with maintaining the schemas, especially if the original author is no longer around. Making it easy to document means we'll hopefully see better documented schemas.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK