Merge pull request #631 from tmihoc/rtd-docs

docs: add docs for RTD

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

@@ -0,0 +1,23 @@
+name: Main Documentation Checks
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs-rtd/**'
+  pull_request:
+    paths:
+      - 'docs-rtd/**'
+  workflow_dispatch:
+    paths:
+      - 'docs-rtd/**'
+
+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-rtd"

.github/workflows/periodic-style-checks.yml

@@ -0,0 +1,19 @@
+name: Periodic Style Checks
+
+on:
+  schedule:
+    - cron: "0 1 * * 4" # Runs at 01:00 AM on every Wednesday
+
+jobs:
+  vale:
+    name: Style checker
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash
+        working-directory: "docs-rtd"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run vale
+        run: |
+          make vale

.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-rtd/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-rtd/.sphinx/requirements.txt

.wokeignore

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

CHANGELOG.md

@@ -11,6 +11,7 @@ ENHANCEMENTS:
 ## 0.15.0 (October 14, 2024)
 
 NOTES:
+
 * **This release requires Juju controller version 2.9.49 or higher juju.**
 * **If using JAAS, this release requires Juju controller version 3.5.0 or higher.**
 * This release uses juju client api code from the juju 3.5.1 release.
@@ -36,6 +37,7 @@ BUG FIXES:
 ## 0.14.0 (September 9, 2024)
 
 NOTES:
+
 * **This release requires juju controller version 2.9.49 or later juju.**
 * This release uses juju client api code from the juju 3.5.1 release.
 
@@ -54,6 +56,7 @@ BUG FIXES:
 ## 0.13.0 (July 15, 2024)
 
 NOTES:
+
 * **This release requires juju controller version 2.9.49 or later juju.**
 * This release uses juju client api code from the juju 3.5.1 release.
 
@@ -72,12 +75,14 @@ BUG FIXES:
 ## 0.12.0 (April 22, 2024)
 
 NOTES:
+
 * **This release requires juju controller version 2.9.49 or later juju.**
 * This release uses juju client api code from the juju 3.5-beta1 candidate release.
 * The added JAAS login enhancements requires Juju controller version 3.5.0 or higher.
 * The added Juju secrets support requires Juju controller version 3.4.0 or higher.
 
 ENHANCEMENTS:
+
 * Support for user secret management is added. You can now use `juju_secret` and `juju_access_secret` resources to create and manage secrets, as well as grant/revoke access to the applications in your plan. You can also use `juju_secret` data source in your configuration to access a secret.
 * Provider config is enhanced with support for Client ID and secret to enable logging in to JAAS using client credentials.
 
@@ -89,6 +94,7 @@ BUG FIXES:
 ## 0.11.0 (March 18, 2024)
 
 NOTES:
+
 * **This release requires juju controller version 2.9.47 or later juju.**
 * This release uses juju client api code from the juju 3.3.0 release. 
 
@@ -103,6 +109,7 @@ ENHANCEMENTS:
 applications. This is similar to `juju deploy --bind` and `juju bind` commands.
 
 BUG FIXES:
+
 * Fix upgrade charm revision for application resources by @hmlanigan in https://github.com/juju/terraform-provider-juju/pull/414
 * Fixes Config/Revision update ordering. by @anvial in https://github.com/juju/terraform-provider-juju/pull/407
 * Adds error check to ReadModel function by @anvial in https://github.com/juju/terraform-provider-juju/pull/416

README.md

@@ -74,12 +74,14 @@ export TF_LOG_PROVIDER=TRACE ; export TF_LOG_PATH=./terraform.log
 Run your terraform commands.
 
 To find logs specific to the juju provider code:
+
 ```shell
 grep "@module=juju.resource" ./terraform.log
 grep "@module=juju.datasource" ./terraform.log
 ```
 
 To find logs specific to the juju client talking to juju itself:
+
 ```shell
 grep "@module=juju.client" ./terraform.log
-```
+```

docs-rtd/.custom_wordlist.txt

@@ -0,0 +1,16 @@
+CIDRs
+CPUs
+Hashicorp
+MicroK
+Multipass
+SREs
+TLS
+Terraform
+Unexpose
+declaratively
+juju
+localhost
+macOS
+natively
+terraform
+unexpose

docs-rtd/.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-rtd/.sphinx/.markdownlint.json

@@ -0,0 +1,22 @@
+{
+    "default": false,
+    "MD003": {
+        "style": "atx"
+    },
+    "MD013": false,
+    "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-rtd/.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-rtd/.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-rtd/.sphinx/_templates/header.html

@@ -0,0 +1,52 @@
+<header id="header" class="p-navigation">
+
+  <div class="p-navigation__nav" role="menubar">
+
+    <ul class="p-navigation__links" role="menu">
+
+      <li>
+        <a class="p-logo" href="https://{{ product_page }}" 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>