mudler
commented
2 years ago Starting to thinker with it:
Our packages already support a description field, which main usage is to be displayed over CLI and the package browser.
For specific documentation, my first thought was at comments, but seems golang yaml support for reading comments is very limited https://ubuntu.com/blog/api-v3-of-the-yaml-package-for-go-is-available and seems also a route to a very complex task.
I would go over creating something simple, living in cos-docs which generates .md files from a template scanning this repository content.
Preferably, for easy of maintaining/writing it should be reading from a specific field in the definition.yaml files, for e.g. documentation (which could contain valid md/html code), so we have:
name: "foo"
category: "bar"
version: "1.0"
description: "What this package do in simple words (keep it under 100 chars)"
documentation: |
## Package usage
Here goes a long detailed description on what the package provides and how to use itIn this way we can re-use the information already present in the definition.yaml file to to generate the appropriate page name and metadata (package name, category, etc) IF and only if a documentation field is found in the package definition.yaml
Is your feature request related to a problem? Please describe. A way for users to identify the cos core packages and the features they provide
Describe the solution you'd like A documentation page, or a set of pages that describe the core packages (
meta/core) and the features they provides contextualized with the docs.Would be preferable to keep specific package documentation together the package sources.