micrometer-metrics / micrometer-metrics/micrometer-docs-generator
Metadata file support
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 18
- Forks
- 15
- Avg merge
- 2m
- Merged PRs (30d)
- 6
Description
Currently, docs-gen can only generate asciidoc files based on the existing source code files.
To make this project more useful, also as raised in #80, it should support metadata files.
docs-gen project(or else) should do two things:
- Generate metadata for the current project source-code
- Generate documentation from metadata
For metadata, it would be something like this:
```json
{
"name": "spring-framework",
"spans": [...]
"metrics": [...]
}
```
The creation of documentation should be able to specify what groups of metadata to be included/excluded.
For example, a doc is created with all metadata or specific metadata files in the classpath or file system.
Things to consider:
* Define metadata format
This could be based on the current model classes(`SpanEntry`, `MetricEntry`, `ObservationConventionEntry`)
* Hookup the docs-gen to maven and gradle lifecycle
In order to include the metadata files in the generating jar, the metadata generation needs to happen before jar creation.
* Allow manual metadata
Similar to `additional-spring-configuration-metadata` in Spring Boot, allows users to provide a manual metadata file.
* Resolve model classes from metadata
When the' ObservationConvention' class references classes in dependent jars, those jars may have metadata files.
The referenced model resolution needs to be extended to consider the metadata files in jars in addition to the source files within the project.
* Metadata inclusion/exclusion
When generating documents, provide filtering(include/exclude) by jar files(?), metadata name, package, etc.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the current model classes SpanEntry, MetricEntry, and ObservationConventionEntry and define how they map to the proposed metadata format. Then trace the docs-gen generation flow and Maven/Gradle lifecycle requirements; done means metadata can be generated, consumed for documentation, manually supplied, resolved from dependent jars, and filtered for inclusion or exclusion.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100