open-telemetry / open-telemetry/weaver

Markdown doc creation should only create links to defined arguments

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

Nobody has claimed this yet.

Dominant language
Rust
Stars
486
Forks
108
Avg merge
3d 4h
Merged PRs (30d)
40

Description

Describe the bug
I've updated my template to use semconv 1.37.0 and now my markdown docs are being generated with an Entities link, but there are no entities in my attributes.yaml.
This is just resulting in a broken link.

To Reproduce
Steps to reproduce the behavior:

  1. Clone the sample:

    git clone git@github.com:jerbly/weaver-example.git
    
    cd weaver-example
    
  2. Update the registry_manifest.yaml to use semconv 1.37.0.

  3. Generate the markdown. I've used docker, by running:

    docker run --rm \
        --mount 'type=bind,source=./model,target=/home/weaver/model' \
        --mount 'type=bind,source=./docs,target=/home/weaver/docs' \
        otel/weaver:v0.17.1 \
        registry generate \
        -r model \
        --templates "https://github.com/open-telemetry/semantic-conventions/archive/refs/tags/v1.37.0.zip[templates]" \
        markdown docs
    
  4. When the docs are created, check the docs/README.md and you will find a new link at the bottom of the file:

    - [Entities](entities/README.md)
    

    But there is no entities/README.md file, resulting in a broken link.

Expected behavior

The markdown docs should create a markdown only with what I have defined in the attributes.yaml.

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

Reproduce the issue with the linked weaver-example, semconv 1.37.0, and the registry generate command, then inspect the markdown generation path that creates docs/README.md. Compare the generated links with the definitions in attributes.yaml; done means no entities/README.md link is emitted when no entities are defined.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.