new: Add generated documentation website

[lgarber-akamai]

📝 Description

This pull request implements a new generated documentation site that is automatically pushed to GitHub Pages.

The below preview URLs can be preview the documentation site in your browser:

• Latest Commit: https://lgarber-akamai.github.io/linode-cli/new/doc-generation/
• Latest Release: https://lgarber-akamai.github.io/linode-cli/latest

---

Rendering

This PR uses Sphinx with the Read the Docs theme to render documentation. The Sphinx configuration and all relevant static files are stored under the docs directory.

Command Documentation Generation

Due to the complexity and abundance of CLI commands, the logic to generate documentation pages for CLI commands is located in the linodecli/documentation directory.

The linodecli/documentation/templates directory contains various Jinja2 templates which are dynamically rendered using the structures defined in linodecli/documentation/template_data.py.

CLI documentation pages are rendered to a user-defined directory when linode-cli generate-docs is called. This is an indirect dependency of the make generate-docs target, which will automatically render the command documentation into the docs/_generated directory before executing any Sphinx commands.

---

Publishing

To automatically publish the documentation to a publicly available URL, this PR adds a new documentation.yml GitHub Actions workflow file.

This workflow has three jobs:

1. Build the documentation and upload it as an artifact

   • This runs on all pushes and PRs.

2. Pull down the built docs from the first step and commit them to the _documentation branch

   • This only runs on releases and pushes to trusted branches (main, dev)
   • The _documentation branch automatically be created if it does not already exist.
     • This branch should be manually configured with force-push protections in place.
     • GitHub pages should be manually configured to publish from the this branch branch.

3. Pull down the built docs from the first step and upload them as a release asset.

   • This only runs on releases.

The Documentation Branch

This PR uses a dedicated documentation branch because it allows us to make multiple versions of the documentation available at at time. Additionally, this allows us to manually rebase any sensitive/unwanted documentation details.

This branch stores all relevant versions as subdirectories, with the latest directory and index.html files being updated on-demand by job #2 (mentioned above).

✔️ Testing

The following test steps assume you have pulled down this PR locally and run make install.

Unit Testing

make testunit

---

Documentation Rendering

1. Build the documentation for the Linode CLI locally using the generate-docs target:

make generate-docs

2. Ensure the documentation generates successfully.

3. Open the documentation index in your browser:

file:///path/to/my/linode-cli/docs/build/html/index.html

4. Ensure all documentation is as expected.

---

Publishing

1. Create a new/doc-generation branch on your fork containing the changes from this PR:

git checkout -b new/doc-generation
git push -u fork new/doc-generation

2. Ensure the Build and Commit to Pages Branch jobs under the Build Documentation workflow run successfully under your fork.
3. Navigate to the Settings -> Pages page of your fork.
4. Set the source to Deploy from a branch, the target branch to the _documentation branch, and the path to / (root).
5. Save your changes and wait for the rendered documentation to become available at MYGHUSERNAME.github.io/linode-cli/new/doc-generation.
6. Ensure version in the top-left reflects the latest commit on your new/doc-generation branch.
7. Publish a release pointing at your fork's new/doc-generation branch with the format vX.X.X.
8. Wait for the release's documentation to become available at MYGHUSERNAME.github.io/linode-cli/latest.
9. Ensure the version in the top-left reflects the published version.

---

📷 Preview

Configuration Page

Create Command	Update Command

View Command	List Command

[lgarber-akamai]

I split this into multiple functions so we can extract the generated usage text for use in the docs

[lgarber-akamai]

I overhauled the logic in this function to account for some new cases I ran into

[lgarber-akamai]

This was updated to store one mostly unchanged version and one fully formatted version of the description, giving us more flexibility in the docs

[lgarber-akamai]

These changes allow us to construct a mock CLI from a custom spec in unit tests

[lgarber-akamai]

This doesn't live with the rest of the util functions because it can also be used in the command --help pages