Skip to content

Commit f426f93

Browse files
bensmrsbensmrs
committed
doc: Contributing section restructuring
Signed-off-by: Benjamin Somers <[email protected]>
1 parent 65ae9b1 commit f426f93

File tree

6 files changed

+129
-122
lines changed

6 files changed

+129
-122
lines changed

‎doc/contributing.md

Lines changed: 6 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,9 @@
1-
# How to contribute to Incus
1+
# Contributing to Incus
22

3-
% Include content from [../CONTRIBUTING.md](../CONTRIBUTING.md)
4-
```{include} ../CONTRIBUTING.md
5-
:start-after: <!-- Include start contributing -->
6-
:end-before: <!-- Include end contributing -->
7-
```
8-
9-
## Contribute to the code
10-
11-
Follow the steps below to set up your development environment to get started working on new features for Incus.
12-
13-
### Install Incus from source
14-
15-
To build the dependencies, follow the instructions in {ref}`installing_from_source`.
16-
17-
### Add your fork as a remote
18-
19-
After setting up your build environment, add your GitHub fork as a remote:
20-
21-
git remote add myfork [email protected]:<your_username>/incus.git
22-
git remote update
23-
24-
Then switch to it:
25-
26-
git checkout myfork/main
3+
```{toctree}
4+
:maxdepth: 1
275
28-
### Build Incus
29-
30-
Finally, you should be able to run `make` inside the repository and build your fork of the project.
31-
32-
At this point, you most likely want to create a new branch for your changes on your fork:
33-
34-
```bash
35-
git checkout -b [name_of_your_new_branch]
36-
git push myfork [name_of_your_new_branch]
6+
Introduction </contributing/introduction>
7+
Contribute to the code </contributing/code>
8+
Contribute to the documentation </contributing/docs>
379
```
38-
39-
### Important notes for new Incus contributors
40-
41-
- Persistent data is stored in the `INCUS_DIR` directory, which is generated by `incus admin init`.
42-
The `INCUS_DIR` defaults to `/var/lib/incus`.
43-
- As you develop, you may want to change the `INCUS_DIR` for your fork of Incus so as to avoid version conflicts.
44-
- Binaries compiled from your source will be generated in the `$(go env GOPATH)/bin` directory by default.
45-
- You will need to explicitly invoke these binaries (not the global `incusd` you may have installed) when testing your changes.
46-
- You may choose to create an alias in your `~/.bashrc` to call these binaries with the appropriate flags more conveniently.
47-
- If you have a `systemd` service configured to run the Incus daemon from a previous installation of Incus, you may want to disable it to avoid version conflicts.
48-
49-
## Contribute to the documentation
50-
51-
We want Incus to be as easy and straight-forward to use as possible.
52-
Therefore, we aim to provide documentation that contains the information that users need to work with Incus, that covers all common use cases, and that answers typical questions.
53-
54-
You can contribute to the documentation in various different ways.
55-
We appreciate your contributions!
56-
57-
Typical ways to contribute are:
58-
59-
- Add or update documentation for new features or feature improvements that you contribute to the code.
60-
We'll review the documentation update and merge it together with your code.
61-
- Add or update documentation that clarifies any doubts you had when working with the product.
62-
Such contributions can be done through a pull request or through a post in the [Tutorials](https://discuss.linuxcontainers.org/c/tutorials/16) section on the forum.
63-
New tutorials will be considered for inclusion in the docs (through a link or by including the actual content).
64-
- To request a fix to the documentation, open a documentation issue on [GitHub](https://github.com/lxc/incus/issues).
65-
We'll evaluate the issue and update the documentation accordingly.
66-
- Post a question or a suggestion on the [forum](https://discuss.linuxcontainers.org).
67-
We'll monitor the posts and, if needed, update the documentation accordingly.
68-
- Ask questions or provide suggestions in the `#lxc` channel on [IRC](https://web.libera.chat/#lxc).
69-
Given the dynamic nature of IRC, we cannot guarantee answers or reactions to IRC posts, but we monitor the channel and try to improve our documentation based on the received feedback.
70-
71-
% Include content from [README.md](README.md)
72-
```{include} README.md
73-
:start-after: <!-- Include start docs -->
74-
```
75-
76-
When you open a pull request, a preview of the documentation output is built automatically.
77-
78-
### Automatic documentation checks
79-
80-
GitHub runs automatic checks on the documentation to verify the spelling, the validity of links, correct formatting of the Markdown files, and the use of inclusive language.
81-
82-
You can (and should!) run these tests locally as well with the following commands:
83-
84-
- Check the spelling: `make doc-spellcheck`
85-
- Check the validity of links: `make doc-linkcheck`
86-
- Check the Markdown formatting: `make doc-lint`
87-
- Check for inclusive language: `make doc-woke`
88-
89-
To run the above, you will need the following:
90-
91-
- Python 3.8 or higher
92-
- The `venv` python package
93-
- The `aspell` tool for spellchecking
94-
- The `mdl` markdown lint tool
95-
96-
### Document configuration options
97-
98-
```{note}
99-
We are currently in the process of moving the documentation of configuration options to code comments.
100-
At the moment, not all configuration options follow this approach.
101-
```
102-
103-
The documentation of configuration options is extracted from comments in the Go code.
104-
Look for comments that start with `gendoc:generate` in the code.
105-
106-
When you add or change a configuration option, make sure to include the required documentation comment for it.
107-
108-
Then run `make generate-config` to re-generate the `doc/config_options.txt` file.
109-
The updated file should be checked in.
110-
111-
The documentation includes sections from the `doc/config_options.txt` to display a group of configuration options.
112-
For example, to include the core server options:
113-
114-
````
115-
% Include content from [config_options.txt](config_options.txt)
116-
```{include} config_options.txt
117-
:start-after: <!-- config group server-core start -->
118-
:end-before: <!-- config group server-core end -->
119-
```
120-
````
121-
122-
If you add a configuration option to an existing group, you don't need to do any updates to the documentation files.
123-
The new option will automatically be picked up.
124-
You only need to add an include to a documentation file if you are defining a new group.

‎doc/contributing/code.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Contribute to the code
2+
3+
Follow the steps below to set up your development environment to get started working on new features for Incus.
4+
5+
## Install Incus from source
6+
7+
To build the dependencies, follow the instructions in {ref}`installing_from_source`.
8+
9+
## Add your fork as a remote
10+
11+
After setting up your build environment, add your GitHub fork as a remote:
12+
13+
git remote add myfork [email protected]:<your_username>/incus.git
14+
git remote update
15+
16+
Then switch to it:
17+
18+
git checkout myfork/main
19+
20+
## Build Incus
21+
22+
Finally, you should be able to run `make` inside the repository and build your fork of the project.
23+
24+
At this point, you most likely want to create a new branch for your changes on your fork:
25+
26+
```bash
27+
git checkout -b [name_of_your_new_branch]
28+
git push myfork [name_of_your_new_branch]
29+
```
30+
31+
## Important notes for new Incus contributors
32+
33+
- Persistent data is stored in the `INCUS_DIR` directory, which is generated by `incus admin init`.
34+
The `INCUS_DIR` defaults to `/var/lib/incus`.
35+
- As you develop, you may want to change the `INCUS_DIR` for your fork of Incus so as to avoid version conflicts.
36+
- Binaries compiled from your source will be generated in the `$(go env GOPATH)/bin` directory by default.
37+
- You will need to explicitly invoke these binaries (not the global `incusd` you may have installed) when testing your changes.
38+
- You may choose to create an alias in your `~/.bashrc` to call these binaries with the appropriate flags more conveniently.
39+
- If you have a `systemd` service configured to run the Incus daemon from a previous installation of Incus, you may want to disable it to avoid version conflicts.

‎doc/contributing/docs.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contribute to the documentation
2+
3+
We want Incus to be as easy and straight-forward to use as possible.
4+
Therefore, we aim to provide documentation that contains the information that users need to work with Incus, that covers all common use cases, and that answers typical questions.
5+
6+
You can contribute to the documentation in various different ways.
7+
We appreciate your contributions!
8+
9+
Typical ways to contribute are:
10+
11+
- Add or update documentation for new features or feature improvements that you contribute to the code.
12+
We'll review the documentation update and merge it together with your code.
13+
- Add or update documentation that clarifies any doubts you had when working with the product.
14+
Such contributions can be done through a pull request or through a post in the [Tutorials](https://discuss.linuxcontainers.org/c/tutorials/16) section on the forum.
15+
New tutorials will be considered for inclusion in the docs (through a link or by including the actual content).
16+
- To request a fix to the documentation, open a documentation issue on [GitHub](https://github.com/lxc/incus/issues).
17+
We'll evaluate the issue and update the documentation accordingly.
18+
- Post a question or a suggestion on the [forum](https://discuss.linuxcontainers.org).
19+
We'll monitor the posts and, if needed, update the documentation accordingly.
20+
- Ask questions or provide suggestions in the `#lxc` channel on [IRC](https://web.libera.chat/#lxc).
21+
Given the dynamic nature of IRC, we cannot guarantee answers or reactions to IRC posts, but we monitor the channel and try to improve our documentation based on the received feedback.
22+
23+
% Include content from [README.md](README.md)
24+
```{include} README.md
25+
:start-after: <!-- Include start docs -->
26+
```
27+
28+
When you open a pull request, a preview of the documentation output is built automatically.
29+
30+
## Automatic documentation checks
31+
32+
GitHub runs automatic checks on the documentation to verify the spelling, the validity of links, correct formatting of the Markdown files, and the use of inclusive language.
33+
34+
You can (and should!) run these tests locally as well with the following commands:
35+
36+
- Check the spelling: `make doc-spellcheck`
37+
- Check the validity of links: `make doc-linkcheck`
38+
- Check the Markdown formatting: `make doc-lint`
39+
- Check for inclusive language: `make doc-woke`
40+
41+
To run the above, you will need the following:
42+
43+
- Python 3.8 or higher
44+
- The `venv` python package
45+
- The `aspell` tool for spellchecking
46+
- The `mdl` markdown lint tool
47+
48+
## Document configuration options
49+
50+
```{note}
51+
We are currently in the process of moving the documentation of configuration options to code comments.
52+
At the moment, not all configuration options follow this approach.
53+
```
54+
55+
The documentation of configuration options is extracted from comments in the Go code.
56+
Look for comments that start with `gendoc:generate` in the code.
57+
58+
When you add or change a configuration option, make sure to include the required documentation comment for it.
59+
60+
Then run `make generate-config` to re-generate the `doc/config_options.txt` file.
61+
The updated file should be checked in.
62+
63+
The documentation includes sections from the `doc/config_options.txt` to display a group of configuration options.
64+
For example, to include the core server options:
65+
66+
````
67+
% Include content from [config_options.txt](config_options.txt)
68+
```{include} config_options.txt
69+
:start-after: <!-- config group server-core start -->
70+
:end-before: <!-- config group server-core end -->
71+
```
72+
````
73+
74+
If you add a configuration option to an existing group, you don't need to do any updates to the documentation files.
75+
The new option will automatically be picked up.
76+
You only need to add an include to a documentation file if you are defining a new group.

‎doc/contributing/introduction.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# How to contribute to Incus
2+
3+
% Include content from [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
4+
```{include} ../../CONTRIBUTING.md
5+
:start-after: <!-- Include start contributing -->
6+
:end-before: <!-- Include end contributing -->
7+
```

‎doc/general.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ Install Incus </installing>
1010
Initialize Incus </howto/initialize>
1111
Get support </support>
1212
Frequently asked </faq>
13-
Contribute to Incus </contributing>
1413
```
1514

1615
You can find a series of demos and tutorials on YouTube:

‎doc/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,5 +58,6 @@ Clustering </clustering>
5858
API </api>
5959
Security </security>
6060
Internals </internals>
61+
Contributing to Incus </contributing>
6162
External resources </external_resources>
6263
```

0 commit comments

Comments
 (0)