docs: add sphinx documentation

Add a sphinx documentation project in the doc folder of Juju. Add the developer docs to it, doing some minimal editing to make them display correctly. Auto generate the CLI docs. This is done in custom_conf.py and the output is in doc/user/cli.
SimonRichardson · Nov 11, 2024 · 5cef4d1 · 5cef4d1
1 parent 761a39c
commit 5cef4d1
Show file tree

Hide file tree

Showing 311 changed files with 11,895 additions and 210 deletions.
diff --git a/.github/workflows/docs-sphinx-python-dependency-build-checks.yml b/.github/workflows/docs-sphinx-python-dependency-build-checks.yml
@@ -0,0 +1,54 @@
+# The purpose of this workflow file is to confirm that the Sphinx
+# virtual environment can be built from source, consequently documenting
+# the packages required in the build environment to do that.
+#
+# This is needed because some projects embeds the documentation into built
+# artifacts which involves rendering the documentation on the target
+# architecture.
+#
+# Depending on the architecture, pip may or may not have already built wheels
+# available, and as such we need to make sure building wheels from source can
+# succeed.
+name: Check and document build requirements for Sphinx venv
+on:
+  - push
+  - pull_request
+  - workflow_dispatch
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          set -ex
+          sudo apt -y install \
+            cargo \
+            libpython3-dev \
+            libxml2-dev \
+            libxslt1-dev \
+            make \
+            python3-venv \
+            rustc
+
+      - name: Install local Juju to generate CLI docs
+        shell: bash
+        run: |
+          make go-install
+
+      - name: Build Sphinx venv
+        run: |
+          set -ex
+          cd docs
+          make -f Makefile.sp \
+            sp-install \
+            PIPOPTS="--no-binary :all:" \
+            || ( cat .sphinx/venv/pip_install.log && exit 1 )
diff --git a/doc/CONTRIBUTING.md → CONTRIBUTING.md b/doc/CONTRIBUTING.md → CONTRIBUTING.md
@@ -10,7 +10,7 @@ great.
   - Check that your patch is [targeting the correct branch](#branches) -
     if not, please rebase it.
   - Please [sign the CLA](#contributor-licence-agreement) if you haven't already.
-  - Use the checklist on the [pull request template](../PULL_REQUEST_TEMPLATE.md#checklist)
+  - Use the checklist on the [pull request template](PULL_REQUEST_TEMPLATE.md#checklist)
     to check you haven't forgotten anything.
 
 Contents
@@ -32,7 +32,7 @@ Issue tracker: https://bugs.launchpad.net/juju/+bugs
 
 Documentation:
 * https://juju.is/docs
-* [source tree docs](doc/)
+* [source tree docs](docs/dev)
 
 Community:
 * https://chat.charmhub.io
@@ -445,6 +445,28 @@ Required dependencies for full static analysis are:
  - go
  - golangci-lint
 
+Documentation
+=============
+
+Juju's documentation is stored in the `doc` directory of the repository. It is
+based on the [Canonical starter
+pack](https://canonical-starter-pack.readthedocs-hosted.com/latest/) and hosted
+on [Read the Docs](https://about.readthedocs.com/).
+
+For general guidance, refer to the [starter pack
+guide](https://canonical-starter-pack.readthedocs-hosted.com/latest/).
+
+For syntax help and guidelines, refer to the [Canonical style
+guides](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/#style-guides).
+
+In structuring, the documentation employs the [Diátaxis](https://diataxis.fr/)
+approach.
+
+To run the documentation locally before submitting your changes:
+```
+make docs-run
+```
+
 Community
 =========
 

diff --git a/Makefile b/Makefile
@@ -681,3 +681,31 @@ static-analysis: dqlite-install-if-missing
 	@cd tests && CGO_ENABLED=1 \
 		CGO_LDFLAGS_ALLOW="(-Wl,-wrap,pthread_create)|(-Wl,-z,now)" \
 		./main.sh static_analysis ${STATIC_ANALYSIS_JOB}
+
+.PHONY: docs
+docs:
+## docs: Displays make commands for docs
+	@echo "\n" \
+        "------------------------------------------------------------- \n" \
+        "* watch, build and serve the documentation:  make docs-run \n" \
+        "* only build:                                make docs-html \n" \
+        "* only serve:                                make docs-serve \n" \
+        "* clean built doc files:                     make docs-clean-doc \n" \
+        "* clean full environment:                    make docs-clean \n" \
+        "* check links:                               make docs-linkcheck \n" \
+        "* check spelling:                            make docs-spelling \n" \
+        "* check spelling (without building again):   make docs-spellcheck \n" \
+        "* check accessibility:                       make docs-pa11y \n" \
+        "* check style guide compliance:              make docs-vale \n" \
+        "* check style guide compliance on target:    make docs-vale TARGET=* \n" \
+        "* check metrics for documentation:           make docs-allmetrics \n" \
+        "------------------------------------------------------------- \n"
+
+.PHONY: docs-help
+docs-help: docs
+
+docs-%:
+## Build the sphinx documentation
+	cd docs && $(MAKE) -f Makefile.sp sp-$* ALLFILES='*.md **/*.md'
+
+
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="doc/juju-logo-dark.png?raw=true">
-  <source media="(prefers-color-scheme: light)" srcset="doc/juju-logo.png?raw=true">
-  <img alt="Juju logo next to the text Canonical Juju" src="doc/juju-logo.png?raw=true" width="30%">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/logos/juju-logo-dark.png?raw=true">
+  <source media="(prefers-color-scheme: light)" srcset="docs/logos/juju-logo.png?raw=true">
+  <img alt="Juju logo next to the text Canonical Juju" src="docs/logos/juju-logo.png?raw=true" width="30%">
 </picture>
 
 Juju is an open source application orchestration engine that enables any application operation (deployment, integration, lifecycle management) on any infrastructure (Kubernetes or otherwise) at any scale (development or production) in the same easy way (typically, one line of code), through special operators called ‘charms’.
@@ -157,4 +157,4 @@ Read our [Code of conduct](https://ubuntu.com/community/code-of-conduct) and:
 ### Make your mark
 
 - Read our [documentation contributor guidelines](https://discourse.charmhub.io/t/documentation-guidelines-for-contributors/1245) and help improve a doc 
-- Read our [codebase contributor guidelines](doc/CONTRIBUTING.md) and help improve the codebase
+- Read our [codebase contributor guidelines](CONTRIBUTING.md) and help improve the codebase
diff --git a/doc/Reviewboard-Tips-and-Tricks.md b/doc/Reviewboard-Tips-and-Tricks.md
diff --git a/doc/dev/how-to/index.md b/doc/dev/how-to/index.md
diff --git a/doc/dev/index.md b/doc/dev/index.md
diff --git a/doc/dev/reference/index.md b/doc/dev/reference/index.md
diff --git a/doc/faq.md b/doc/faq.md
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
diff --git a/docs/.gitignore b/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
diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
@@ -0,0 +1,31 @@
+# .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
+      - make go-install
+
+# 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
diff --git a/docs/.sphinx/.markdownlint.json b/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
+}