micrometer-metrics / micrometer-metrics/micrometer-docs-generator

Metadata file support

Open
#130 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement help wanted
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.