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

Extensible handlebar for custom helpers

Open
#359 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
18
Forks
15
Avg merge
2m
Merged PRs (30d)
6

Description

## Custom Handlebar Helpers for HandlebarUtils

### Background
A few weeks ago, I asked a question in the Slack channel ([link to message](https://micrometer-metrics.slack.com/archives/C662HUJC9/p1741778287996959)) about adding custom HandlebarHelpers to the existing [HandlebarUtils](https://github.com/micrometer-metrics/micrometer-docs-generator/blob/main/micrometer-docs-generator/src/main/java/io/micrometer/docs/commons/templates/HandlebarsUtils.java) string manipulations.

@jonatan-ivanov suggested creating an issue, so I thought I could also provide a possible solution with it. This is just a proposal, so please let me know what you think and how it can be improved.

### Objective
(One small example) I want to cut the package names and keep only the class name of the defining Convention (rendered when using ObservationDocumentation structure).

### Current Workaround
Currently, I achieve this through a Gradle Copy task to filter the end result, similar to how [Spring AMQP handles their documentation](https://github.com/spring-projects/spring-amqp/blob/d8ed48d32048f6e5459f6f9fd951ea1c2a66220e/build.gradle#L545-L552).

I have taken a look in the StringHelpers provided by Handlebars.java but couldn't find what I need. Perhaps I overlooked something.

### Proposed Solution
My approach now is to change HandlebarUtils to a Singleton, making the instance more extensible and allowing custom HandlebarHelpers to be registered. As of my view and tests, this change does not affect current functionality but introduces extensibility.

I've implemented the changes in my [fork](https://github.com/fynnjuranek/micrometer-docs-generator/commit/be995bc6d226d19afafab94bd4bff93ebc0e7d81), do you want me to open a PR?

### Example Usage
I created a simple example demonstrating how to use this, and it worked as intended. If you're interested, please check out the [repository](https://github.com/fynnjuranek/micrometer-plugin-test).

Here's a small peek at how I would add custom helpers:

```java
public class CustomDocsGeneratorCommand {
public static void main(String[] args) {

Handlebars handlebars = HandlebarsUtils.createHandlebars();
handlebars.registerHelpers(CustomHelpers.class);

DocsGeneratorCommand.main(args);
}
}
```
```kotlin
// gradle task
val generateObservabilityDocs by tasks.registering(JavaExec::class) {
mainClass.set("com.example.CustomDocsGeneratorCommand") // use customized main instead of io.micrometer.docs.DocsGeneratorCommand
classpath = configurations.getByName("adoc") + sourceSets.main.get().runtimeClasspath
val conventionsTemplateFile = file("src/main/resources/conventions.adoc.hbs")
val metricsTemplateFile = file("src/main/resources/metrics.adoc.hbs")
val spansTemplateFile = file("src/main/resources/spans.adoc.hbs")
args(
project.layout.projectDirectory.asFile.absolutePath, // Input folder
".*", // Inclusion pattern
project.layout.buildDirectory.get().asFile.absolutePath, // Output folder
"--conventions-template=${conventionsTemplateFile.path}",
"--metrics-template=${metricsTemplateFile.path}",
"--spans-template=${spansTemplateFile.path}",
)
}
```

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 micrometer-docs-generator/src/main/java/io/micrometer/docs/commons/templates/HandlebarsUtils.java and reviewing the proposed changes in the linked fork. Check the existing tests and current helper registration behavior before deciding how custom helpers should be exposed. Done means custom helpers can be registered without changing current functionality, with tests covering the extension.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.