100 lines
4.3 KiB
Markdown
100 lines
4.3 KiB
Markdown
|
|
# Telegraf release and docs build
|
|
|
|
The Telegraf release build process (using code in `influxdata/telegraf-internal`) includes automation for building `influxdata/docs-v2` documentation from `influxdata/telegraf` plugin README files.
|
|
|
|
## Release build process
|
|
|
|
1. Telegraf team triggers the release script, which generates a `docs` binary.
|
|
The binary takes a Telegraf release version tag as an argument.
|
|
2. When executed (by the Telegraf team for an official release or on your local
|
|
system for testing), the binary:
|
|
|
|
a. Clones the `docs-v2` repo and the `telegraf` repo and checks out the specified release tag.
|
|
b. Applies `docs-v2` frontmatter templates (`docs-v2/telegraf-build/templates`) to the `telegraf` plugin README files.
|
|
c. Commits the changes to the local `docs-v2` repo and creates a PR for the changes.
|
|
|
|
## Build Telegraf docs for local testing and preview
|
|
|
|
> [!Warn]
|
|
>
|
|
> Use the following steps for local testing and preview only.
|
|
>
|
|
> _Don't commit the generated files to version control._
|
|
>
|
|
> Submit edits and fixes to the `/influxdata/telegraf` repo.
|
|
> The Telegraf release process triggers documentation builds and
|
|
> submits them to `influxdata/docs-v2` for review.
|
|
>
|
|
|
|
Follow steps to test the Telegraf docs build process and preview generated docs on your local system (not for an official Telegraf release):
|
|
|
|
- [Build using Docker](#build-using-docker)
|
|
- [Build manually](#build-manually)
|
|
|
|
### Run Docker to build Telegraf docs for testing and preview
|
|
|
|
1. If you don't already have an SSH key pair, generate one for your GitHub-associated email address, add your private key to your SSH agent, and add then add the public key to your GitHub account.
|
|
|
|
The Dockerfile leverages Docker's BuildKit and the `--ssh` flag to use your SSH keys for GitHub authentication.
|
|
|
|
1. Open a terminal and navigate to the directory containing the Dockerfile (`./scripts`), then enter the following command to build the Docker image:
|
|
|
|
```bash
|
|
docker build --ssh default -t telegraf-build .
|
|
```
|
|
|
|
2. Run the Docker container using the built image and mount a volume to `/app/repos/docs-v2/telegraf`:
|
|
|
|
```bash
|
|
docker run --rm \
|
|
-v /Users/me/Documents/github/docs-v2/content/telegraf:/app/repos/docs-v2/content/telegraf \
|
|
telegraf-build v1.33.0
|
|
```
|
|
|
|
Replace `/Users/me/Documents/github/docs-v2/content/telegraf` with the actual path on your host machine where you want to access the generated documentation.
|
|
|
|
### Manually build Telegraf docs for testing and preview
|
|
|
|
To test manually run the build process on your local system
|
|
(without a release triggered by `influxdata/telegraf`):
|
|
|
|
1. Install a recent version of Go for your system.
|
|
|
|
2. Clone the `influxdata/telegraf-internal` repo to your local system (for example, to `~/Documents/github/telegraf-internal`)
|
|
|
|
3. To generate the release binaries (`telegraf-internal/telegraf_release/bin/`),change into the `~/Documents/github/telegraf-internal` directory and run `make`.
|
|
|
|
4. To generate the documentation, run the `telegraf-internal/telegraf_release/bin/docs` binary and include the Telegraf release tag to build--for example:
|
|
|
|
```bash
|
|
# Change to `telegraf-build` in your local docs-v2 repo.
|
|
cd ~/Documents/github/docs-v2/telegraf-build
|
|
# Run the `docs` binary to generate the documentation.
|
|
~/Documents/github/telegraf-internal/telegraf_release/bin/docs v1.33.0
|
|
```
|
|
|
|
You can skip steps for local testing:
|
|
|
|
```bash
|
|
~/Documents/github/telegraf-internal/telegraf_release/bin/docs -skip changelog,pull-request v1.33.0
|
|
```
|
|
|
|
The binary looks for `.tmpl` template files in `./templates` `telegraf-internal/telegraf_release/docs/templates/`, however we expect to permanently move them to `docs-v2/telegraf-build/templates` soon.
|
|
|
|
The `docs` binary:
|
|
a. Clones the `docs-v2` repo and the `telegraf` repo and checks out the specified Telegraf release tag.
|
|
b. Commits the changes to the local `docs-v2` repo and creates a PR for the changes.
|
|
|
|
5. To test the templates and preview the changes on your local machine, change to `telegraf-build/repos/docs-v2`, install dependencies, and start Hugo:
|
|
|
|
```bash
|
|
cd ~/Documents/github/docs-v2/telegraf-build/repos/docs-v2
|
|
# Install dependencies
|
|
yarn install
|
|
# Start Hugo server
|
|
npx hugo serve
|
|
```
|
|
|
|
Alternatively, copy the generated files your existing local `docs-v2` repo (but, _don't_ commit them to version control).
|