diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6748c2083..e3a171caa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,12 +63,24 @@ Once merged to the main branch, `po` files, `README.md` with the command line re You can also contribute to the documentation. It uses [GitHub Markdown Format](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github). -You can propose modifications in 2 ways: +To contribute to the documentation edit the files in the `/docs/` directory after forking and cloning the repo. +Each page on the [documentation website](https://canonical-adsys.readthedocs-hosted.com/en/stable/) also includes +an edit button for making small changes, such as fixing typos. -* Directly on the repo, in the `doc/` directory. Once merged, this will update the repository wiki automatically. -* Via the [edit wiki link](https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages#editing-wiki-pages) of this repository. Once merged, this will update the main repository automatically. +> [!WARNING] +> Much of the reference documentation in `/docs/reference/` is auto-generated. +> Editing the content of these files requires modifying `.go` and `.yaml` files found elsewhere in the repo. +> Some references are generated using `dconf` keys from upstream packages and cannot be edited. +> Changes made directly to reference files will be overwritten in the automation process. +> If you want to propose a change to a reference page please make your edits in the relevant source files +> or contact someone on the ADSys team if you are uncertain how to do so. -Each page is a different chapter, ordered with numbers, which is available with the command `adsysctl doc`. +Documentation for the AD integration client `adsysctl` can be generated in the terminal with: + +``` +adsysctl doc [CHAPTER] [flags] +``` +Each page is a different chapter ordered with numbers. ## Contributing to the code diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml index 467676ddd..5901cfb50 100644 --- a/docs/.sphinx/spellingcheck.yaml +++ b/docs/.sphinx/spellingcheck.yaml @@ -9,7 +9,8 @@ matrix: - .custom_wordlist.txt output: .sphinx/.wordlist.dic sources: - - _build/**/*.html + # check all docs except technical reference + - _build/**/*.html|!_build/reference/policies/**/*.html pipeline: - pyspelling.filters.html: comments: false @@ -28,3 +29,4 @@ matrix: - img - a.p-navigation__link - a.contributor + - a.reference.internal # don't spellcheck refs hidden in html source diff --git a/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/allow-local-admins.md b/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/allow-local-admins.md deleted file mode 100644 index 360fa461c..000000000 --- a/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/allow-local-admins.md +++ /dev/null @@ -1,25 +0,0 @@ -# Allow local administrators - -This allows or prevents client machine to have local users gaining administrators privilege on the machine. - - -- Type: privilege -- Key: `/allow-local-admins` - -Note: - - * Enabled: This leaves the default rules for the “sudo” and “admin” rule intact. - * Disabled: This denies root privileges to the predefined administrator groups (sudo and admin). - - -An Ubuntu Pro subscription on the client is required to apply this policy. - - - -**Metadata** - -| Element | Value | -| --- | --- | -| Location | `Computer Policies -> Ubuntu -> Client management -> Privilege Authorization -> Allow local administrators` | -| Registry Key | `Software\Policies\Ubuntu\privilege\allow-local-admins` | -| Element type | | -| Class: | Machine | diff --git a/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/client-admins.md b/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/client-admins.md deleted file mode 100644 index 0fd737c4a..000000000 --- a/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/client-admins.md +++ /dev/null @@ -1,26 +0,0 @@ -# Client administrators - -Define users and groups from AD allowed to administer client machines. -It must be of the form `user@domain` or `%group@domain`. One per line. - - -- Type: privilege -- Key: `/client-admins` - -Note: - - * Enabled: This allows defining Active Directory groups and users with administrative privileges in the box entry. - * Disabled: This disallows any Active Directory group or user to become an administrator of the client even if it is defined in a parent GPO of the hierarchy tree. - - -An Ubuntu Pro subscription on the client is required to apply this policy. - - - -**Metadata** - -| Element | Value | -| --- | --- | -| Location | `Computer Policies -> Ubuntu -> Client management -> Privilege Authorization -> Client administrators` | -| Registry Key | `Software\Policies\Ubuntu\privilege\client-admins` | -| Element type | multiText | -| Class: | Machine | diff --git a/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/index.md b/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorization/index.md similarity index 71% rename from docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/index.md rename to docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorization/index.md index 36a874fb7..838832342 100644 --- a/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/index.md +++ b/docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorization/index.md @@ -1,4 +1,4 @@ -# Privilege Authorisation +# Privilege Authorization ```{toctree} :maxdepth: 99 diff --git a/docs/reference/policies/Computer Policies/Ubuntu/Client management/index.md b/docs/reference/policies/Computer Policies/Ubuntu/Client management/index.md index c64b103e1..b26eb6335 100644 --- a/docs/reference/policies/Computer Policies/Ubuntu/Client management/index.md +++ b/docs/reference/policies/Computer Policies/Ubuntu/Client management/index.md @@ -5,7 +5,7 @@ Computer Scripts/index Power Management/index -Privilege Authorisation/index +Privilege Authorization/index System Drive Mapping/index System proxy configuration/index System-wide application confinement/index