cloudmesh-ai-theme 7.0.1

Theme for Cloudmesh AI documentation

Cloudmesh AI Theme Guide

Welcome to the guide for the Cloudmesh AI Theme. This package provides a consistent look and feel for Cloudmesh AI project documentation, built as an extension of the Material for MkDocs theme.

Table of Contents

• Introduction
• Installation
• Usage
  • Primary Method (Recommended)
  • Configuration Options
  • Alternative: Manual Asset Deployment
• Development & Contribution
  • Local Development
  • Running Tests
• Maintainer's Guide
  • Project Structure
  • Version Management
  • Release Process

---

Introduction

The cloudmesh-ai-theme is a Python package that provides branding for Cloudmesh AI documentation. Instead of copying CSS and images into every project, this package allows you to apply the theme via a configuration change in your mkdocs.yml.

It automatically handles:

• Branding: Injects the "Cloudmesh AI" site name and a standardized footer.
• Styling: Applies custom CSS.
• Assets: Provides shared logos and favicons.

---

Installation

The theme is distributed as a Python package. You can install it using pip:

pip install cloudmesh-ai-theme

---

Usage

Primary Method (Recommended)

The simplest way to use the theme is to specify it by name in your mkdocs.yml file. This method automatically applies all branding, styles, and assets.

theme:
  name: cloudmesh-ai-theme

Configuration Options

You can customize the theme while maintaining the Cloudmesh AI layout. Currently, the following options are supported:

primary_color

Change the primary accent color of the theme.

theme:
  name: cloudmesh-ai-theme
  primary_color: "#ff0000" # Example: Red

logo and favicon

You can override the default Cloudmesh AI logo and favicon by specifying their paths in your mkdocs.yml. SVG favicons are recommended for better scalability and quality.

theme:
  name: cloudmesh-ai-theme
  logo: assets/my-logo.png
  favicon: assets/my-favicon.svg

Alternative: Manual Asset Deployment

If you need direct access to the CSS and image files within your project directory (e.g., for further local overrides), you can deploy the assets manually.

1. Run the deployment command:

   cloudmesh-ai-theme-install
   

   This will copy the assets into docs/theme/ in your current project.

2. Reference assets in mkdocs.yml:

   extra_css:
     - theme/custom.css
   
   theme:
     favicon: theme/assets/favicon.svg
     logo: theme/assets/logo-white.png
     name: material
   

---

Development & Contribution

Local Development

To make changes to the theme and see them reflected in your projects immediately, install the package in editable mode:

cd cloudmesh-ai-theme
pip install -e .

Running Tests

The theme includes a verification suite to ensure that the package builds and renders correctly.

cd cloudmesh-ai-theme/tests
python test_theme.py

---

Maintainer's Guide

Project Structure

cloudmesh-ai-theme/
├── .github/workflows/  # CI/CD pipelines
├── src/
│   └── cloudmesh_ai_theme/
│       ├── __init__.py  # Package logic & versioning
│       ├── assets/      # Logos and favicons
│       ├── css/         # Custom stylesheets
│       └── theme/       # MkDocs templates (main.html)
├── tests/              # Verification suite
├── VERSION             # Single source of truth for version
├── pyproject.toml      # Build system & metadata
└── README.md           # This guide

Version Management

The version is managed in the VERSION file at the root of the repository. To bump the version:

1. Edit the VERSION file (e.g., change 0.1.0 to 0.1.1).
2. Commit the change:

   git add VERSION
   git commit -m "Bump version to 0.1.1"
   

Release Process

Releases are automated via GitHub Actions. To trigger a new release:

1. Create a git tag following the v* pattern:

   git tag v0.1.0
   git push origin v0.1.0
   

2. The GitHub Action will automatically build the .whl and .tar.gz distributions and upload them as artifacts.

Publishing to PyPI

The easiest way to upload the package to PyPI is using the provided Makefile:

make pypi

This command automatically installs the necessary build tools, builds the distribution, and uploads it to PyPI using twine.

Manual Upload (without Makefile):

1. Install build tools:

   pip install build twine
   

2. Build the distribution:

   python -m build
   

3. Upload to PyPI:

   python -m twine upload dist/*
   

Automated Upload (GitHub Actions): To automate publishing, add a pypi-publish step to the .github/workflows/release.yml file and configure a PYPI_API_TOKEN in your GitHub repository secrets.