chore(docs): add instructions for regenerating component docs and lic…

…enses (vectordotdev#17828)
aholmberg · Jun 30, 2023 · 93ef6c3 · 93ef6c3
1 parent 77ac63c
commit 93ef6c3
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 4 deletions.
diff --git a/docs/DEVELOPING.md b/docs/DEVELOPING.md
@@ -123,6 +123,8 @@ Loosely, you'll need the following:
 - **To build Vector:** Have working Rustup, Protobuf tools, C++/C build tools (LLVM, GCC, or MSVC), Python, and Perl, `make` (the GNU one preferably), `bash`, `cmake`, `GNU coreutils`, and `autotools`.
 - **To run integration tests:** Have `docker` available, or a real live version of that service. (Use `AUTOSPAWN=false`)
 - **To run `make check-component-features`:** Have `remarshal` installed.
+- **To run `make check-licenses` or `cargo vdev build licenses`:** Have `rust-license-tool` [installed](https://github.com/DataDog/rust-license-tool).
+- **To run `cargo vdev build component-docs`:** Have `cue` [installed](https://cuelang.org/docs/install/).
 
 If you find yourself needing to run something inside the Docker environment described above, that's totally fine, they won't collide or hurt each other. In this case, you'd just run `make environment-generate`.
 
@@ -156,6 +158,8 @@ cargo bench transforms::example
 # Format your code before pushing!
 make fmt
 cargo fmt
+# Build component documentation for the website
+cargo vdev build component-docs
 ```
 
 If you run `make` you'll see a full list of all our tasks. Some of these will start Docker containers, sign commits, or even make releases. These are not common development commands and your mileage may vary.

diff --git a/docs/DOCUMENTING.md b/docs/DOCUMENTING.md
@@ -9,12 +9,14 @@ documentation in tandem with code changes.
 
 1. [Responsibilities](#responsibilities)
 2. [Reference documentation](#reference-documentation)
-   1. [Formatting](#formatting)
-   2. [Validating](#validating)
+   1. [Installing CUE](#installing-cue)
+   2. [Generating from source code](#generating-from-source-code)
+   3. [Formatting](#formatting)
+   4. [Validating](#validating)
       1. [Tips & tricks](#tips--tricks)
          1. [Make small incremental changes](#make-small-incremental-changes)
-   3. [Changelog](#changelog)
-   4. [Release highlights](#release-highlights)
+   5. [Changelog](#changelog)
+   6. [Release highlights](#release-highlights)
       1. [FAQ](#faq)
          1. [What makes a release highlight noteworthy?](#what-makes-a-release-highlight-noteworthy)
          2. [How is a release highlight different from a blog post?](#how-is-a-release-highlight-different-from-a-blog-post)
@@ -53,6 +55,15 @@ version that Vector depends on. Currently Vector is using `v0.5.0`. Using a CUE
 version different than this may result in CUE check/build errors. We are aiming
 to improve the developer experience around external tool dependencies ([#15909](https://github.com/vectordotdev/vector/issues/15909)).
 
+### Generating from source code
+
+Much of Vector's reference documentation is automatically compiled from source code (e.g., doc comments).
+To regenerate this content, run:
+
+```bash
+cargo vdev build component-docs
+```
+
 ### Formatting
 
 Vector has some CUE-related CI checks that are run whenever changes are made to