Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add prerequisites section for building documentation #1233

Merged

Conversation

javiertoledos
Copy link
Contributor

Missing prerequisites may hinder documentation contributions as it may throw errors when running make doc (specially the Python version) or when trying to validate spellcheck or linting.

Personally I found I had those tools missing when trying to compile the doc first time and Sphinx uses a python notation that is available since 3.8 but the error thrown is cryptic if python version is older.

@github-actions github-actions bot added the Documentation Documentation needs updating label Sep 20, 2024
@stgraber stgraber added the Incomplete Waiting on more information from reporter label Sep 20, 2024
@stgraber
Copy link
Member

Hello,

Before we can review this pull request, we need all the commits to include a suitable Signed-off-by line. You can see CONTRIBUTING.md for more information on that.

Thanks!

@javiertoledos javiertoledos force-pushed the doc/add-required-tools-for-building-doc branch from 2afb3f1 to efb7943 Compare September 21, 2024 00:49
@stgraber
Copy link
Member

.tmp/doc/contributing.md:80: MD004 Unordered list style
.tmp/doc/contributing.md:81: MD004 Unordered list style
.tmp/doc/contributing.md:82: MD004 Unordered list style
.tmp/doc/contributing.md:83: MD004 Unordered list style

Comment on lines 78 to 83
### Prerequisites

* Python 3.8+
* Python venv module
* Aspell (for spellchecking)
* Markdown lint tool (mdl)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should use - here for the list so it matches the style of the others in this file.

Rather than add things like mdl and venv to the wordlist, it's best to just put them in a code block.

Given those requirements are specific to the documentation checking, it's probably best to move them into the Automatic documentation checks section.

So something like:

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.

You can (and should!) run these tests locally as well with the following commands:
- Check the spelling: `make doc-spellcheck`
- Check the validity of links: `make doc-linkcheck`
- Check the Markdown formatting: `make doc-lint`
- Check for inclusive language: `make doc-woke`

To run the above, you will need the following:
- Python 3.8 or higher
- The `venv` python package
- The `aspell` tool for spellchecking
- The `mdl` markdown lint tool

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done, updated doc with comments above.

@javiertoledos javiertoledos force-pushed the doc/add-required-tools-for-building-doc branch from efb7943 to e2e78b9 Compare September 24, 2024 19:03
@stgraber stgraber force-pushed the doc/add-required-tools-for-building-doc branch from e2e78b9 to 14bc978 Compare September 24, 2024 20:24
@stgraber stgraber merged commit 87c628d into lxc:main Sep 24, 2024
30 checks passed
@stgraber
Copy link
Member

thanks!

tmeijn pushed a commit to tmeijn/dotfiles that referenced this pull request Oct 17, 2024
This MR contains the following updates:

| Package | Update | Change |
|---|---|---|
| [lxc/incus](https://github.com/lxc/incus) | minor | `v6.5.0` -> `v6.6.0` |

MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot).

**Proposed changes to behavior should be submitted there as MRs.**

---

### Release Notes

<details>
<summary>lxc/incus (lxc/incus)</summary>

### [`v6.6.0`](https://github.com/lxc/incus/releases/tag/v6.6.0): Incus 6.6

[Compare Source](lxc/incus@v6.5.0...v6.6.0)

### Announcement

https://discuss.linuxcontainers.org/t/incus-6-6-has-been-released/21762

#### What's Changed

-   Fix capitalization in `incus network list` by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1191
-   incusd/storage/drivers/lvm: Cache VG extent size by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1192
-   incusd/network/ovn: LSP dynamic allocation can't be done per protocol by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1195
-   incusd/instance/qemu: Always re-generate the nvram symlink by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1193
-   incusd/instance/qemu: Set O_DIRECT when passing in FDs by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1196
-   Translations update from Hosted Weblate by [@&#8203;weblate](https://github.com/weblate) in lxc/incus#1194
-   incusd/apparmor: Only initialize with the daemon by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1197
-   Various fixes by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1198
-   doc: Fix limits.memory default value unit by [@&#8203;kznrluk](https://github.com/kznrluk) in lxc/incus#1199
-   incusd/storage/zfs: Make sure the zvol is a block device by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1204
-   incusd/apparmor: Don't attempt unloading profiles when apparmor is di… by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1206
-   Translations update from Hosted Weblate by [@&#8203;weblate](https://github.com/weblate) in lxc/incus#1208
-   Translations update from Hosted Weblate by [@&#8203;weblate](https://github.com/weblate) in lxc/incus#1212
-   doc/installing: Add Rocky Linux 9 by [@&#8203;sspencerwire](https://github.com/sspencerwire) in lxc/incus#1213
-   Translations update from Hosted Weblate by [@&#8203;weblate](https://github.com/weblate) in lxc/incus#1219
-   Fix storage volume snapshot listings by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1218
-   internal/server/instance/drivers: Disable 9p and vsock for Windows VMs by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1217
-   Add qcow2 and vmdk support to incus-migrate by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1214
-   scripts: fix empty-incus.sh instances delete by [@&#8203;itviewer](https://github.com/itviewer) in lxc/incus#1222
-   doc/installing: Add link to Arch Wiki for Incus by [@&#8203;simos](https://github.com/simos) in lxc/incus#1227
-   Properly handle `--project` in CLI error messages by [@&#8203;bensmrs](https://github.com/bensmrs) in lxc/incus#1230
-   Allow VMs to pull console history similar to containers by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1228
-   incus/console: Add completion by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1231
-   Various bugfixes by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1236
-   Don't return an error if console log file doesn't exist by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1241
-   incusd/instance/qemu: Properly plumb I/O limits by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1242
-   cleanup: Replace use of os.IsNotExist(err) with errors.Is(err, fs.ErrNotExist) by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1245
-   Allow to use `dns.search` when only IPv4 is enabled by [@&#8203;pmoranga](https://github.com/pmoranga) in lxc/incus#1244
-   apparmor: Allow all mounts in unprivileged containers by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1243
-   doc: add note for Nvidia usage when building from source in OpenSUSE by [@&#8203;javiertoledos](https://github.com/javiertoledos) in lxc/incus#1232
-   Add operating system details to instance state by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1234
-   Translations update from Hosted Weblate by [@&#8203;weblate](https://github.com/weblate) in lxc/incus#1247
-   tests: Don't over-provision test volumes by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1246
-   cmd/incus-migrate: Don't copy converted VM image by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1248
-   doc: add prerequisites section for building documentation by [@&#8203;javiertoledos](https://github.com/javiertoledos) in lxc/incus#1233
-   Fix cross-cluster image transfer by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1249
-   Translations update from Hosted Weblate by [@&#8203;weblate](https://github.com/weblate) in lxc/incus#1250
-   Add OVN load balancer state API by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1251
-   Add missing placement scriptlet calls by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1254
-   VM console log fixes by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1255
-   Fix alias handling by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1256
-   incusd/instance/qemu: Fix issues with old NVRAM by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1257
-   Added ability for user to specify the macvlan mode using the mode key… by [@&#8203;farsonic](https://github.com/farsonic) in lxc/incus#1258
-   Translations update from Hosted Weblate by [@&#8203;weblate](https://github.com/weblate) in lxc/incus#1269
-   Allows the VM's limits.memory configuration to be set to a percentage value by [@&#8203;itviewer](https://github.com/itviewer) in lxc/incus#1270
-   incusd/network/ovn: Fix CIDR size check by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1271
-   incusd/instance/lxc: Mount /run if the path exists by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1275
-   Run cluster evacuate and restore in parallel by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1262
-   Documentation fixes by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1276
-   client: Capture original OCI image identifier by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1277
-   docs: mention alpine edge repository in alpine installation by [@&#8203;thebigbone](https://github.com/thebigbone) in lxc/incus#1260
-   Change incus file delete operation to sftp by [@&#8203;HassanAlsamahi](https://github.com/HassanAlsamahi) in lxc/incus#1266
-   Translations update from Hosted Weblate by [@&#8203;weblate](https://github.com/weblate) in lxc/incus#1279
-   Allow fully creating LVM cluster pools through the API by [@&#8203;gibmat](https://github.com/gibmat) in lxc/incus#1278
-   Allow adding external interfaces to an OVN network by [@&#8203;SpiffyEight77](https://github.com/SpiffyEight77) in lxc/incus#1263
-   Fix VM race conditions by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1280
-   Various bugfixes by [@&#8203;stgraber](https://github.com/stgraber) in lxc/incus#1283

#### New Contributors

-   [@&#8203;kznrluk](https://github.com/kznrluk) made their first contribution in lxc/incus#1199
-   [@&#8203;sspencerwire](https://github.com/sspencerwire) made their first contribution in lxc/incus#1213
-   [@&#8203;gibmat](https://github.com/gibmat) made their first contribution in lxc/incus#1217
-   [@&#8203;itviewer](https://github.com/itviewer) made their first contribution in lxc/incus#1222
-   [@&#8203;pmoranga](https://github.com/pmoranga) made their first contribution in lxc/incus#1244
-   [@&#8203;javiertoledos](https://github.com/javiertoledos) made their first contribution in lxc/incus#1232
-   [@&#8203;farsonic](https://github.com/farsonic) made their first contribution in lxc/incus#1258
-   [@&#8203;thebigbone](https://github.com/thebigbone) made their first contribution in lxc/incus#1260

**Full Changelog**: lxc/incus@v6.5.0...v6.6.0

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this MR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box

---

This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy40NDAuNyIsInVwZGF0ZWRJblZlciI6IjM3LjQ0MC43IiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJSZW5vdmF0ZSBCb3QiXX0=-->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Documentation needs updating Incomplete Waiting on more information from reporter
Development

Successfully merging this pull request may close these issues.

2 participants