# Generating Reference Documentation for Metrics

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->

This page demonstrates the generation of metrics reference documentation.

## Before you begin


	<h3 id="requirements">Requirements:<a class="td-heading-self-link" href="#requirements" aria-label="Heading self-link"></a></h3>
<ul>
<li>
<p>You need a machine that is running Linux or macOS. On Windows, use
<a href="https://learn.microsoft.com/en-us/windows/wsl/install">Windows Subsystem for Linux (WSL)</a>,
since the build tooling relies on <code>make</code> and Bash scripts.</p>
</li>
<li>
<p>You need to have these tools installed:</p>
<ul>
<li><a href="https://git-scm.com/book/en/v2/Getting-Started-Installing-Git">Git</a></li>
<li><a href="https://go.dev/dl/">Go</a>, any recent release (Go downloads the exact toolchain a generator needs automatically)</li>
<li><a href="https://www.gnu.org/software/make/">make</a></li>
<li><a href="https://gcc.gnu.org/">gcc compiler/linker</a></li>
<li><a href="https://docs.docker.com/engine/installation/">Docker</a> (required only for the local website preview with <code>make container-serve</code>)</li>
</ul>
</li>
<li>
<p>You need to know how to create a pull request to a GitHub repository.
This involves creating your own fork of the repository. For more
information, see <a href="/docs/contribute/new-content/open-a-pr/#fork-the-repo">Work from a local clone</a>.</p>
</li>
</ul>


<!-- steps -->

## Clone the Kubernetes repository

The metric generation happens in the Kubernetes repository.
To clone the repository, change directories to where you want the clone to exist.

Then, execute the following command:

```shell
git clone https://www.github.com/kubernetes/kubernetes 
```

This creates a `kubernetes` folder in your current working directory.

## Generate the metrics

Inside the cloned Kubernetes repository, locate the
`test/instrumentation/documentation` directory.
The metrics documentation is generated in this directory.

With each release, new metrics are added.
After you run the metrics documentation generator script, copy the
metrics documentation to the Kubernetes website and
publish the updated metrics documentation.

To generate the latest metrics, make sure you are in the root of the cloned Kubernetes directory.
Then, execute the following command:

```shell
./test/instrumentation/update-documentation.sh
```

To check for changes, execute:

```shell
git status
```

The output is similar to:

```
./test/instrumentation/documentation/documentation.md
./test/instrumentation/documentation/documentation-list.yaml
```

## Copy the generated metrics documentation file to the Kubernetes website repository

1. Set the Kubernetes website root environment variable.

   Execute the following command to set the website root:

   ```shell
   export WEBSITE_ROOT=<path to website root>
   ```

2. Copy the generated metrics file to the Kubernetes website repository.

   ```shell
   cp ./test/instrumentation/documentation/documentation.md "${WEBSITE_ROOT}/content/en/docs/reference/instrumentation/metrics.md"
   ```

   
<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>If you get an error, check that you have permission to copy the file.
You can use <code>chown</code> to change the file ownership back to your own user.</div>


## Create a pull request

To create a pull request, follow the instructions in [Opening a pull request](/docs/contribute/new-content/open-a-pr/).

## What's next

* [Contribute-upstream](/docs/contribute/generate-ref-docs/contribute-upstream/)
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)