OctoPrint-Uptime Plugin Documentation¶

This directory contains the documentation for the OctoPrint-Uptime plugin.

Overview¶

OctoPrint-Uptime is a plugin for OctoPrint that displays both system and OctoPrint process uptime in the navbar and About → System dialog, and provides an API endpoint for retrieving uptime information. It supports internationalization (English/German), configurable polling intervals, optional compact toggle mode, and integration with the OctoPrint frontend.

Quick Start¶

Prerequisites¶

OctoPrint 1.10.0+ (Python 3.8+)
Node.js 20+ (for frontend development)
mkdocs (for documentation)

Installation¶

Install the plugin via the OctoPrint Plugin Manager or pip:

pip install "https://github.com/Ajimaru/OctoPrint-Uptime/archive/main.zip"

Restart OctoPrint.

Usage¶

System and OctoPrint process uptime can be displayed independently or together in the navbar (with optional compact alternating mode, which shows one line and alternates system and OctoPrint uptime).
API endpoint: /api/plugin/octoprint_uptime returns both system uptime fields (seconds, uptime, uptime_dhm, uptime_dh, uptime_d) and separate OctoPrint process uptime fields (octoprint_seconds, octoprint_uptime, octoprint_uptime_dhm, octoprint_uptime_dh, octoprint_uptime_d).
uptime_dhm: Shows days, hours, and minutes (e.g., "2d 3h 45m" or "1h 30m" if zero days). Leading zero days are omitted, but hours and minutes are always shown even if zero.
uptime_dh: Shows days and hours (e.g., "2d 3h" or "5h" if zero days). Leading zero days are omitted, but hours are always shown even if zero.
uptime_d: Shows days only (e.g., "2d" or "0d").
The API returns all formatted strings; display_format only selects which returned variant the frontend displays.
Configuration: Settings → Plugin OctoPrint-Uptime

API Example¶

{
  "seconds": 3600,
  "uptime": "1h 0m 0s",
  "uptime_dhm": "1h 0m",
  "uptime_dh": "1h",
  "uptime_d": "0d",
  "octoprint_seconds": 3450,
  "octoprint_uptime": "57m 30s",
  "octoprint_uptime_dhm": "0h 57m",
  "octoprint_uptime_dh": "0h",
  "octoprint_uptime_d": "0d",
  "display_format": "dhm",
  "poll_interval_seconds": 5
}

Development¶

Requirements¶

Python 3.12+ (for development, linting, and building)
Node.js 20+ (for frontend development)
python3-venv (or equivalent virtual environment tool)

Setup¶

Install the appropriate requirements for your purpose:

For development (tests, linters, build tools):

pip install -r requirements-dev.txt

For building the documentation (mkdocs + docs tooling), create a separate virtual environment to avoid dependency conflicts:

python3 -m venv venv-docs
source venv-docs/bin/activate  # On Windows: venv-docs\Scripts\activate
pip install -r requirements-docs.txt

For runtime/production installs (OctoPrint runtime dependencies), use the top-level requirements.txt:

pip install -r requirements.txt

Important: Use separate virtual environments for development (venv) and documentation (venv-docs) to avoid version conflicts, as requirements-dev.txt and requirements-docs.txt have overlapping dependencies (pylint, ruff).

Install Node.js dependencies for frontend tooling when needed:

npm install

Build & Serve¶

# Generate JavaScript API docs
./scripts/generate-jsdocs.sh

# Serve locally (with live reload)
mkdocs serve
# Open http://localhost:8000

# Build static site
mkdocs build
# Output in site/

Documentation Structure¶

docs/
├── README.md                         # Documentation README
├── index.md                          # Overview page (this file)
├── getting-started.md                # Development setup
├── jsdoc.json                        # jsdoc-to-markdown config used by scripts/generate-jsdocs.sh
├── architecture/                     # System design
│   ├── overview.md                   # Architecture overview
│   ├── data-flow.md                  # Data flow diagrams
│   ├── algorithms.md                 # Uptime algorithms
│   ├── settings.md                   # Settings reference
│   └── octoprint-integration.md      # Plugin integration
├── api/                              # API reference
│   ├── python.md                     # Python API (mkdocstrings placeholder + intro)
│   └── javascript.md                 # JavaScript API (generated by scripts/generate-jsdocs.sh)
├── frontend/                         # Frontend docs
│   ├── ui-placements.md              # UI integration
│   └── i18n.md                       # Internationalization
├── development/                      # Developer guides
│   ├── contributing.md               # Contributing guide (synced with top-level CONTRIBUTING.md)
│   ├── testing.md                    # Testing guide (commands, coverage)
│   └── release-process.md            # Release process for maintainers
└── reference/                        # Reference docs
    ├── configuration.md             # Configuration reference
    ├── cli-dev-scripts.md           # Dev scripts reference
    ├── frontend.md                  # Frontend reference
    └── diagrams/
        ├── overview.md              # Conceptual diagram (Mermaid)
        ├── classes.md               # UML class diagram (auto-generated, SVG generated during CI)
        ├── classes_detailed.md      # Detailed UML class diagram (auto-generated, SVG generated during CI)
        ├── packages.md              # Package diagram (auto-generated, SVG generated during CI)
        └── REGENERATE.md            # Instructions to regenerate diagrams locally

Diagrams

- The conceptual Mermaid overview and auto-generated UML diagram markdown files are available in `reference/diagrams/`.
- SVG diagrams are auto-generated during CI/documentation builds.
- Open `reference/diagrams/overview.md` for the conceptual diagram overview and links to generated diagram markdown files.

Technology Stack¶

MkDocs - Static site generator
Material for MkDocs - Material Design theme
mkdocstrings - Python API documentation
jsdoc-to-markdown - JavaScript API documentation

Auto-generation¶

Python API¶

Python API documentation is automatically generated from docstrings using mkdocstrings.

To update:

Add/update docstrings in Python files
Run mkdocs build

JavaScript API¶

JavaScript API documentation is generated from JSDoc comments during the documentation build.

To update:

Add JSDoc comments to JavaScript files
Run ./scripts/generate-jsdocs.sh
The script generates docs/api/javascript.md (which is generated but not committed).

Example JSDoc comment:

/**
 * Fetch uptime information from the OctoPrint-Uptime plugin API.
 *
 * @async
 * @function fetchUptime
 * @param {string} [baseUrl='/'] - OctoPrint base URL (must include protocol when remote)
 * @returns {Promise<{
 *   seconds: number,
 *   uptime: string,
 *   uptime_dhm: string,
 *   uptime_dh: string,
 *   uptime_d: string,
 *   octoprint_seconds: number,
 *   octoprint_uptime: string,
 *   octoprint_uptime_dhm: string,
 *   octoprint_uptime_dh: string,
 *   octoprint_uptime_d: string,
 *   display_format: string,
 *   poll_interval_seconds: number
 * }|null>} Parsed uptime object or null on error
 */
async function fetchUptime(baseUrl = "/") {
  try {
    const url = new URL("/api/plugin/octoprint_uptime", baseUrl).toString();
    const res = await fetch(url, {
      credentials: "same-origin",
      headers: { Accept: "application/json" },
    });
    if (!res.ok) return null;
    return await res.json();
  } catch (err) {
    console.error("OctoPrint-Uptime: fetchUptime failed", err);
    return null;
  }
}

Deployment¶

Documentation is automatically deployed to GitHub Pages on push to main branch.

Workflow: .github/workflows/docs.yml

Developer guides¶

The developer-facing pages under docs/development/ have been synchronized with the repository CONTRIBUTING.md and tests/README.md and include details on the scripts/ helper scripts. See the development section in the docs for contributor, testing and release guidance.

Configuration¶

mkdocs.yml¶

Main configuration file for MkDocs:

Theme settings
Navigation structure
Plugin configuration
Markdown extensions

jsdoc.json¶

Configuration for JavaScript documentation:

Source file patterns
Output format
Plugins

Writing Documentation¶

Style Guide¶

Use Markdown for all documentation
Include code examples where appropriate
Add diagrams using Mermaid for complex flows
Link between related pages
Keep language clear and concise

Markdown Extensions¶

Available extensions:

Admonitions: !!! note "Title"
Code blocks: ```python with syntax highlighting
Tables: Standard Markdown tables
Mermaid diagrams: ```mermaid
Tabbed content: Custom tabs

Example: Admonition¶

!!! warning "Important"
This is a warning message.

!!! note
This is a note without a title.

Example: Mermaid Diagram¶

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

Example: Code Block¶

```python
def example():
    """Example function."""
    return "Hello, World!"
```

Local Development¶

Watch Mode¶

MkDocs automatically rebuilds on file changes:

mkdocs serve

Build Only¶

mkdocs build

Clean Build¶

rm -rf site/
mkdocs build

Troubleshooting¶

"Module not found" errors¶

pip install -r requirements-docs.txt

"npx: command not found"¶

npm install

JavaScript docs empty¶

The JavaScript source files need JSDoc comments. See "Auto-generation" section above.

Build warnings¶

Some warnings are expected (e.g., missing type annotations). These don't prevent the build.

Port already in use¶

mkdocs serve -a localhost:8001