1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<!--
---
title: "Contributing to documentation"
custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/contributing/contributing-documentation.md
---
-->
# Contributing to documentation
We welcome contributions to Netdata's already extensive documentation, which we host at
[docs.netdata.cloud](https://docs.netdata.cloud/) and store inside of the [main
repository](https://github.com/netdata/netdata) on GitHub.
Like all contributing to all other aspects of Netdata, we ask that anyone who wants to help with documentation read and
abide by the [Contributor Convenant Code of Conduct](/CODE_OF_CONDUCT.md) and follow the
instructions outlined in our [Contributing document](/CONTRIBUTING.md).
We also ask you to read our [documentation style guide](style-guide.md), which, while not complete, will give you some
guidance on how we write and organize our documentation.
All our documentation uses the Markdown syntax. If you're not familiar with how it works, please read the [Markdown
introduction post](https://daringfireball.net/projects/markdown/) by its creator, followed by [Mastering
Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub.
## How contributing to the documentation works
There are two ways to contribute to Netdata's documentation:
1. Edit documentation [directly in GitHub](#edit-documentation-directly-on-github).
2. Download the repository and [edit documentation locally](#edit-documentation-locally).
Editing in GitHub is a simpler process and is perfect for quick edits to a single document, such as fixing a typo or
clarifying a confusing sentence.
Editing locally is more complex, as you need to download the Netdata repository and build the documentation using
`mkdocs`, but allows you to better organize complex projects. By building documentation locally, you can preview your
work using a local web server before you submit your PR.
In both cases, you'll finish by submitting a pull request (PR). Once you submit your PR, GitHub will initiate a number
of jobs, including a Netlify preview. You can use this preview to view the documentation site with your changes applied,
which might help you catch any lingering issues.
To continue, follow one of the paths below:
- [Edit documentation directly in GitHub](#edit-documentation-directly-on-github)
- [Edit documentation locally](#edit-documentation-locally)
## Edit documentation directly on GitHub
Start editing documentation on GitHub by clicking the small pencil icon on any page on Netdata's [documentation
site](https://docs.netdata.cloud/). You can find them at the top of every page.
Clicking on this icon will take you to the associated page in the `netdata/netdata` repository. Then click the small
pencil icon on any documentation file (those ending in the `.md` Markdown extension) in the `netdata/netdata`
repository.
If you know where a file resides in the Netdata repository already, you can skip the step of beginning on the
documentation site and go directly to GitHub.
Once you've clicked the pencil icon on GitHub, you'll see a full Markdown version of the file. Make changes as you see
fit. You can use the `Preview changes` button to ensure your Markdown syntax is working properly.
Under the `Propose file change` header, write in a descriptive title for your requested change. Beneath that, add a
concise descrition of what you've changed and why you think it's important. Then, click the `Propose file change`
button.
After you've hit that button, jump down to our instructions on [pull requests and
cleanup](#pull-requests-and-final-steps) for your next steps.
!!! note This process will create a branch directly on the `netdata/netdata` repository, which then requires manual
cleanup. If you're going to make significant documentation contributions, or contribute often, we recommend the
local editing process just below.
## Edit documentation locally
Editing documentation locally is the preferred method for complex changes, PRs that span across multiple documents, or
those that change the styling or underlying functionality of the documentation.
Here is the workflow for editing documentation locally. First, create a fork of the Netdata repository, if you don't
have one already. Visit the [Netdata repository](https://github.com/netdata/netdata) and click on the `Fork` button in
the upper-right corner of the window.
GitHub will ask you where you want to clone the repository, and once finished you'll end up at the index of your forked
Netdata repository. Clone your fork to your local machine:
```bash
git clone https://github.com/YOUR-GITHUB-USERNAME/netdata.git
```
You can now jump into the directory and explore Netdata's structure for yourself.
### Understanding the structure of Netdata's documentation
All of Netdata's documentation is stored within the repository itself, as close as possible to the code it corresponds
to. Many sub-folders contain a `README.md` file, which is then used to populate the documentation about that
feature/component of Netdata.
For example, the file at `packaging/installer/README.md` becomes `https://docs.netdata.cloud/packaging/installer/` and
is our installation documentation. By co-locating it with quick-start installtion code, we ensure documentation is
always tightly-knit with the functions it describes.
You might find other `.md` files within these directories. The `packaging/installer/` folder also contains `UPDATE.md`
and `UNINSTALL.md`, which become `https://docs.netdata.cloud/packaging/installer/update/` and
`https://docs.netdata.cloud/packaging/installer/uninstall/`, respectively.
If the documentation you're working on has a direct correlation to some component of Netdata, place it into the correct
folder and either name it `README.md` for generic documentation, or with another name for very specific instructions.
#### The `docs` folder
At the root of the Netdata repository is a `docs/` folder. Inside this folder we place documentation that does not have
a direct relationship to a specific component of Netdata. It's where we house our [getting started
guide](/docs/getting-started.md), guides on [running Netdata behind Nginx](/docs/Running-behind-nginx.md), and more.
If the documentation you're working on doesn't have a direct relaionship to a component of Netdata, it can be placed in
this `docs/` folder.
### Make your edits
Now that you're set up and understand where to find or create your `.md` file, you can now begin to make your edits.
Just use your favorite editor and keep in mind our [style guide](style-guide.md) as you work.
If you add a new file to the documentation, you may need to modify the `buildyaml.sh` file to ensure it's added to the
site's navigation. This is true for any file added to the `docs/` folder.
Be sure to periodically add/commit your edits so that you don't lose your work! We use version control software for a
reason.
### Build the documentation
Building the documentation periodically gives you a glimpse into the final product, and is generally required if you're
making changes to the table of contents.
We have a [netdata/docs Docker Image](https://hub.docker.com/r/netdata/os-test) available on the Docker Hub
that greatly simplifies building the documentation on any [Docker](https://www.docker.com) supported platform.
To build the docs using this image via Docker simply run the following commands in your shell:
```bash
cd /path/to/netdata
docker run -i -t -v $PWD:/netdata netdata/docs
```
----
if you are using a GNU/Linux based system for developing / contribiting to our documentation, you may build the
docs with the provided Shell scripts in `./docs/generator/buildhtml.sh`. This requires GNU Bash and findutils
as well as Python/pip and some Python packages `mkdocs` and `mkdocs-material` installed in your environment.
Follow the [Python installation instructions](https://www.python.org/downloads/) for your machine.
Use `pip`, which was installed alongside Python, to install `mkdocs` and `mkdocs-material`. Your operating system might
force you to use `pip2` or `pip3` instead, depending on which version of Python you have installed.
```bash
pip install mkdocs mkdocs-material --user
```
> If you're having trouble with the installation of Python, `mkdocs`, or `mkdocs-material`, try looking into the
> `mkdocs` [installation instructions](https://squidfunk.github.io/mkdocs-material/getting-started/#installation).
When `pip` is finished installing, navigate to the root directory of the Netdata repository and run the documentation
generator script.
```bash
sh docs/generator/buildhtml.sh
```
This process will take some time. Once finished, the built documentation site will be located at
`docs/generator/build/`.
### Run a local web server to test documentation
The best way to view the documentation site you just built is to run a simple web server from the
`docs/generator/build/` directory. So, navigate there and run a Python-based web server:
```sh
cd docs/generator/build/
python3 -m http.server 20000
```
Feel free to replace the port number you want this web server to listen on (port `20000` in this case (only one higher
than the agent!)).
Open your web browser and navigate to `http://localhost:20000`. If you replaced the port earlier, change it here as
well. You can now navigate through the documentation as you would on the live site!
## Pull requests and final steps
When you're finished with your changes, add and commit them to your fork of the Netdata repository. Head over to GitHub
to create your pull request (PR).
Once we receive your pull request (PR), we'll take time to read through it and assess it for correctness, conciseness,
and overall quality. We may point to specific sections and ask for additional information or other fixes.
## What's next
- Read up on the Netdata documentation [style guide](style-guide.md).
[](<>)
|
