Contributing to the docs
editContributing to the docs
editThe Beats documentation follows the tagging guidelines described in the Docs HOWTO. However it extends these capabilities in a couple ways:
- The documentation makes extensive use of AsciiDoc conditionals to provide content that is reused across multiple books. This means that there might not be a single source file for each published HTML page. Some files are shared across multiple books, either as complete pages or snippets. For more details, refer to Where to find the Beats docs source.
-
The documentation includes some files that are generated from YAML source or
pieced together from content that lives in
_meta
directories under the code (for example, the module and exported fields documentation). For more details, refer to Generated docs.
Where to find the Beats docs source
editBecause the Beats documentation makes use of shared content, doc generation scripts, and componentization, the source files are located in several places:
Documentation | Location of source files |
---|---|
Main docs for the Beat, including index files |
|
Shared docs and Beats Platform Reference |
|
Processor docs |
|
Output docs |
|
Module docs |
|
The conf.yaml file in the
docs
repo shows all the resources used to build each book. This file is used
to drive the classic docs build and is the source of truth for file locations.
If you can’t find the source for a page you want to update, go to the published page at www.elastic.co and click the Edit link to navigate to the source.
The Beats documentation build also has dependencies on the following files in the docs repo:
-
shared/versions/stack/<version>.asciidoc
-
shared/attributes.asciidoc
Generated docs
editAfter updating docs.asciidoc
files in _meta
directories, you must run the
doc collector scripts to regenerate the docs.
Make sure you
set up your Beats development environment and use
the correct Go version. The Go version is listed in the version.asciidoc
file
for the branch you want to update.
To run the docs collector scripts, change to the beats directory and run:
make update
The make update
command overwrites files in the docs
directories
without warning. If you accidentally update a generated file and run
make update
, your changes will be overwritten.
To format your files, you might also need to run this command:
make fmt
The make command calls the following scripts to generate the docs:
auditbeat/scripts/docs_collector.py generates:
-
auditbeat/docs/modules_list.asciidoc
-
auditbeat/docs/modules/*.asciidoc
filebeat/scripts/docs_collector.py generates:
-
filebeat/docs/modules_list.asciidoc
-
filebeat/docs/modules/*.asciidoc
metricbeat/scripts/mage/docs_collector.go generates:
-
metricbeat/docs/modules_list.asciidoc
-
metricbeat/docs/modules/*.asciidoc
libbeat/scripts/generate_fields_docs.py generates
-
auditbeat/docs/fields.asciidoc
-
filebeat/docs/fields.asciidoc
-
functionbeat/docs/fields.asciidoc
-
heartbeat/docs/fields.asciidoc
-
metricbeat/docs/fields.asciidoc
-
packetbeat/docs/fields.asciidoc
-
winlogbeat/docs/fields.asciidoc