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"
+}