linode · lgarber-akamai · Aug 28, 2024 · Aug 30, 2024 · Aug 30, 2024 · Aug 30, 2024
@@ -0,0 +1,151 @@
+name: Build Documentation
+
+on:
+  push:
+    branches:
+      - "**"
+    tags-ignore:
+      - "v*"
+  pull_request:
+  release:
+    types:
+      - published
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: "recursive"
+
+      - name: Update system packages
+        run: sudo apt-get update -y
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+
+      - name: Install Python dependencies and update cert
+        run: |
+          pip install wheel boto3 && \
+          pip install certifi -U && \
+          pip install .[obj,dev]
+
+      - name: Resolve the target CLI version
+        uses: actions/github-script@v7
+        id: resolve-cli-version
+        with:
+          script: |
+            const latest_release = await github.rest.repos.getLatestRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo
+            });
+
+            if (context.payload.release && latest_release.data.id == context.payload.release.id) {
+              let result = context.payload.release.tag_name;
+
+              if (result.startsWith('v')) {
+                result = result.slice(1);
+              }
+
+              return result;
+            }
+
+            return '0.0.0.dev+' + context.sha.substring(0, 7);
+          result-encoding: string
+
+      - name: Build the documentation
+        run: make create-version && make generate-docs
+        env:
+          # We need to define a token to prevent the CLI from
+          # attempting to do a first-time configuration.
+          LINODE_CLI_TOKEN: foobar
+          LINODE_CLI_VERSION: ${{ steps.resolve-cli-version.outputs.result }}
+
+      - name: Upload the artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: generated-docs-html
+          path: docs/build/html
+
+  pages-commit:
+    name: Commit to Pages Branch
+    runs-on: ubuntu-latest
+    needs:
+      - build
+    # Make sure we avoid a race condition =)
+    concurrency:
+      group: "docs-stage"
+      cancel-in-progress: false
+    permissions:
+      contents: write
+
+    if: (github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'dev' || github.ref_name == 'new/doc-generation' )) || (github.ref_type == 'tag')
+    steps:
+      - name: Checkout the documentation branch
+        continue-on-error: true
+        id: checkout-docs
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: "recursive"
+          ref: "_documentation"
+
+      - name: Create the documentation branch if it does not already exist
+        if: "${{ steps.checkout-docs.outcome != 'success' }}"
+        run: git switch --orphan _documentation
+
+      - name: Ensure any previous documentation for this branch is removed
+        run: rm -rf "./${{ github.ref_name }}"
+
+      - name: Download the artifact from the build job
+        uses: actions/download-artifact@v4
+        with:
+          name: generated-docs-html
+          path: "${{ github.ref_name }}"
+
+      - name: Override the latest version if necessary
+        if: ${{ github.ref_type == 'tag' }}
+        run: |
+          rm -rf latest && cp -r ${{ github.ref_name }} latest
+
+      - name: Overlay static files
+        run: |
+          echo "<head><meta http-equiv='refresh' content='0; URL=latest/index.html'></head>" > index.html;
+          touch .nojekyll
+
+      - name: Commit and push this change
+        run: |
+          git config user.name "Documentation Publisher";
+          git config user.email "[email protected]";
+          git add .;
+          git commit --allow-empty -m "Build ${{ github.ref_name }} from ${{ github.sha }}";
+          git push origin _documentation;
+
+  upload-release-asset:
+    name: Upload Release Asset
+    runs-on: ubuntu-latest
+    needs:
+      - build
+    if: github.ref_type == 'tag'
+    steps:
+      - name: Download the artifact from the previous job
+        uses: actions/download-artifact@v4
+        with:
+          name: generated-docs-html
+          path: ".build/${{ github.ref_name }}"
+
+      - name: Archive the built documentation
+        run: |
+          cd .build/${{ github.ref_name }} && tar -czvf ../documentation.tar.gz *
+
+      - name: Upload the documentation as a release asset
+        uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191
+        with:
+          files: .build/documentation.tar.gz
+          tag_name: ${{ github.ref_name }}
@@ -14,3 +14,4 @@ test/.env
 MANIFEST
 venv
 openapi*.yaml
+_generated
@@ -9,6 +9,8 @@ ifdef TEST_CASE
 TEST_CASE_COMMAND = -k $(TEST_CASE)
 endif
 
+# TODO: Remove this workaround once the LKE docs issue has been resolved
+SPEC := https://gist.githubusercontent.com/lgarber-akamai/3e1d77f08acf1a7b29d63a77b0b4a289/raw/12f18d7b7b54cf8587c9f24e72509b0e530e5760/openapi.yaml
 
 SPEC_VERSION ?= latest
 ifndef SPEC
@@ -20,6 +22,10 @@ VERSION_FILE := ./linodecli/version.py
 VERSION_MODULE_DOCSTRING ?= \"\"\"\nThe version of the Linode CLI.\n\"\"\"\n\n
 LINODE_CLI_VERSION ?= "0.0.0.dev"
 
+# Documentation-related variables
+SPHINX_BUILDER ?= html
+SPHINX_GENERATED_PATH := ./docs/_generated
+
 .PHONY: install
 install: check-prerequisites requirements build
 	pip3 install --force dist/*.whl
@@ -82,6 +88,18 @@ testall:
 .PHONY: test
 test: testunit
 
+.PHONY: clean-docs-commands
+clean-docs-commands:
+	rm -rf "$(SPHINX_GENERATED_PATH)"
+
+.PHONY: generate-docs
+generate-docs-commands: bake clean-docs-commands
+	python3 -m linodecli generate-docs "$(SPHINX_GENERATED_PATH)"
+
+.PHONY: generate-docs
+generate-docs: generate-docs-commands
+	cd docs && make $(SPHINX_BUILDER)
+
 .PHONY: black
 black:
 	black linodecli tests

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -0,0 +1,8 @@
+Commands
+========
+
+..  toctree::
+    :maxdepth: 4
+    :glob:
+
+    ../_generated/groups/*
@@ -0,0 +1,40 @@
+import json
+from pathlib import Path
+
+DOCS_PATH = Path(__file__).parent.resolve()
+BUILD_META_PATH = DOCS_PATH / "_generated" / "build_meta.json"
+
+if not BUILD_META_PATH.is_file():
+    raise FileNotFoundError(
+        "Could not find build_meta file. "
+        "Was `linode-cli generate-docs` run before attempting to render this documentation?",
+    )
+
+with open(BUILD_META_PATH, "r") as f:
+    build_meta = json.load(f)
+
+# Project information
+project = "linode-cli"
+copyright = "2024, Akamai Technologies Inc."
+author = "Akamai Technologies Inc."
+version = f"v{build_meta.get('cli_version')} (API v{build_meta.get('api_spec_version')})"
+
+# General configuration
+extensions = ["sphinx_rtd_theme"]
+source_suffix = ".rst"
+exclude_patterns = []
+highlight_language = "bash"
+templates_path = ["templates"]
+
+# HTML builder configuration
+html_logo = "static/logo.svg"
+html_favicon = "static/favicon.ico"
+html_static_path = ["static"]
+html_css_files = [
+    "overlay.css"
+]
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "style_nav_header_background": "#009CDE"
+}