docs: migrate authd docs to Sphinx and RTD

.github/workflows/automatic-doc-checks.yml

@@ -0,0 +1,18 @@
+name: Main Documentation Checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Manual trigger
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: "./docs"

.wokeignore

@@ -0,0 +1 @@
+docs/.wokeignore

CONTRIBUTING.md

@@ -1,11 +1,13 @@
-# Contributing to authd
+<!-- Include start contributing intro -->
+# Contributing to Authd
 
 A big welcome and thank you for considering making a contribution to authd and Ubuntu! It’s people like you that help make these products a reality for users in our community.
 
 By agreeing to follow these guidelines the contribution process should be easy and effective for everyone involved. This also communicates that you agree to respect the time of the developers working on this project. In return, we will reciprocate that respect by addressing your issues, assessing proposed changes and helping you finalise your pull requests.
 
-These are mostly guidelines, not rules. Use your best judgment and feel free to propose changes to this document in a pull request.
+These are mostly guidelines, not rules. Use your best judgement and feel free to propose changes to this document in a pull request.
 
+<!-- Include end contributing intro -->
 ## Quicklinks
 
 - [Contributing to authd](#contributing-to-authd)
@@ -27,9 +29,10 @@ These are mostly guidelines, not rules. Use your best judgment and feel free to
   - [Contributor License Agreement](#contributor-license-agreement)
   - [Getting help](#getting-help)
 
+<!-- Include start contributing main -->
 ## Code of conduct
 
-We take our community seriously, holding ourselves and other contributors to high standards of communication. By contributing to this project you agree to uphold the Ubuntu community [Code of Conduct](https://ubuntu.com/community/code-of-conduct).
+We take our community seriously, holding ourselves and other contributors to high standards of communication. By contributing to this project you agree to uphold the Ubuntu community [Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct).
 
 ## Getting Started
 
@@ -54,7 +57,7 @@ PRs to our project are always welcome and can be a quick way to get your fix or
 * Only fix/add the functionality in question **OR** address wide-spread whitespace/style issues, not both.
 * Add unit or integration tests for fixed or changed functionality.
 * Address a single concern in the least possible number of changed lines.
-* Include documentation in the repo or on our [docs site](https://github.com/canonical/authd/wiki).
+* Include documentation in the repo or on our [docs site](https://github.com/ubuntu/authd/wiki).
 * Be accompanied by a complete Pull Request template (loaded automatically when a PR is created).
 
 For changes that address core functionality or that would require breaking changes (e.g. a major release), it's best to open an Issue to discuss your proposal first. This is not required but can save time when creating and reviewing changes.
@@ -115,7 +118,7 @@ Then build the Debian package:
 debuild --prepend-path=${HOME}/.cargo/bin
 ```
 
-The debian packages are available in the parent directory.
+The Debian packages are available in the parent directory.
 
 #### Building authd only
 
@@ -152,7 +155,7 @@ This last command will produce two libraries (`./pam/pam_authd.so` and `./pam/go
 These modules must be copied to `/usr/lib/$(gcc -dumpmachine)/security/` while the executable must be copied to `/usr/libexec/authd-pam`.
 
 For further information about the PAM module architecture and testing see the
-[PAM Hacking](./pam/Hacking.md) page.
+[PAM Hacking](https://github.com/ubuntu/authd/blob/main/pam/Hacking.md) page.
 
 #### Building the NSS module only
 
@@ -196,8 +199,10 @@ You only need to sign this once and if you have previously signed the agreement
 
 An automated test is executed on PRs to check if this agreement has been accepted.
 
-This project is covered by [THIS LICENSE](LICENSE).
+<!-- TODO: add license. -->
+<!-- This project is covered by [THIS LICENSE](LICENSE). -->
 
 ## Getting help
 
 Join us in the [Ubuntu Community](https://discourse.ubuntu.com/c/desktop/8) and post your question there with a descriptive tag.
+<!-- Include end contributing main -->

docs/.custom_wordlist.txt

@@ -0,0 +1,36 @@
+amd
+auth
+authd
+biometric
+DBus
+entra
+GDM
+GIDs
+gRPC
+github
+grpc
+https
+io
+msentraid
+NFS
+nss
+OIDC
+OpenID
+ppa
+PR
+protoc
+PRs
+repo
+smartcard
+sshd
+styleguide
+sudo
+TPM
+ubuntu
+UID
+UIDs
+unix
+vendorize
+vhs
+webview
+whitespace

docs/.gitignore

@@ -0,0 +1,17 @@
+
+# Starter pack rules start here
+/*env*/
+.sphinx/venv/
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/.doctrees/
+.sphinx/node_modules/
+package*.json
+_build
+.DS_Store
+__pycache__
+.idea/
+.vscode/
+.sphinx/styles/*
+.sphinx/vale.ini
+sp-docs/_build

docs/.readthedocs.yaml

@@ -0,0 +1,30 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    pre_install:
+      - git fetch --unshallow || true
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: docs/.sphinx/requirements.txt

docs/.sphinx/.markdownlint.json

@@ -0,0 +1,16 @@
+{
+    "default": false,
+    "MD003": { "style": "atx" },
+    "MD013": { "code_blocks": false, "tables": false, "stern": true, "line_length": 150},
+    "MD014": true,
+    "MD018": true,
+    "MD022": true,
+    "MD023": true,
+    "MD026": { "punctuation": ".,;。，；"},
+    "MD031": { "list_items": false},
+    "MD032": true,
+    "MD035": true,
+    "MD042": true,
+    "MD045": true,
+    "MD052": true
+}

docs/.sphinx/.wordlist.txt

@@ -0,0 +1,64 @@
+ACME
+ACME's
+addons
+AGPLv
+API
+APIs
+balancer
+Charmhub
+CLI
+DCO
+Diátaxis
+Dqlite
+dropdown
+EBS
+EKS
+enablement
+favicon
+Furo
+Git
+GitHub
+Grafana
+IAM
+installable
+JSON
+Juju
+Kubeflow
+Kubernetes
+Launchpad
+linter
+LTS
+LXD
+Makefile
+Makefiles
+Matrix
+Mattermost
+MicroCeph
+MicroCloud
+MicroOVN
+MyST
+namespace
+namespaces
+NodePort
+Numbat
+observability
+OEM
+OLM
+Permalink
+pre
+Quickstart
+ReadMe
+reST
+reStructuredText
+roadmap
+RTD
+subdirectories
+subfolders
+subtree
+TODO
+Ubuntu
+UI
+UUID
+VM
+webhook
+YAML

docs/.sphinx/_static/css/pdf.css

@@ -0,0 +1,15 @@
+/* Only relevant for specific PDF generation issues */
+
+.rubric>.hclass2 {
+    display: block;
+    font-size: 2em;
+    border-radius: .5rem;
+    font-weight: 300;
+    line-height: 1.25;
+    margin-top: 1.75rem;
+    margin-right: -0.5rem;
+    margin-bottom: 0.5rem;
+    margin-left: -0.5rem;
+    padding-left: .5rem;
+    padding-right: .5rem;
+}

docs/.sphinx/_templates/header.html

@@ -0,0 +1,54 @@
+<header id="header" class="p-navigation">
+
+  <div class="p-navigation__nav" role="menubar">
+
+    <ul class="p-navigation__links" role="menu">
+
+      <li>
+        <!-- NOTE: changed anchor to span until product_page exists -->
+        <!-- <a class="p-logo" href="https://{{ product_page }}" aria-current="page"> -->
+        <span class="p-logo" aria-current="page">
+          <img src="{{ pathto(product_tag,1) }}" alt="Logo" class="p-logo-image">
+          <div class="p-logo-text p-heading--4">{{ project }}
+          </div>
+        </a>
+      </li>
+
+      <li class="nav-ubuntu-com">
+        <a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
+      </li>
+
+      <li>
+        <a href="#" class="p-navigation__link nav-more-links">More resources</a>
+        <ul class="more-links-dropdown">
+
+          {% if discourse %}
+          <li>
+            <a href="{{ discourse }}" class="p-navigation__sub-link p-dropdown__link">Discourse</a>
+          </li>
+          {% endif %}
+
+          {% if mattermost %}
+          <li>
+            <a href="{{ mattermost }}" class="p-navigation__sub-link p-dropdown__link">Mattermost</a>
+          </li>
+          {% endif %}
+
+          {% if matrix %}
+          <li>
+            <a href="{{ matrix }}" class="p-navigation__sub-link p-dropdown__link">Matrix</a>
+          </li>
+          {% endif %}
+
+          {% if github_url %}
+          <li>
+            <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+          </li>
+          {% endif %}
+
+        </ul>
+      </li>
+
+    </ul>
+  </div>
+</header>