ophix-docs 2026.10.4.1__tar.gz

ophix_docs-2026.10.4.1/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: ophix-docs
+Version: 2026.10.4.1
+Summary: Inline markdown documentation plugin for Ophix fleet management servers
+Author: Ophix Project
+License-Expression: MIT
+Project-URL: Homepage, https://ophix.io
+Project-URL: Documentation, https://github.com/ophixproject/ophix-docs#readme
+Project-URL: Source, https://github.com/ophixproject/ophix-docs
+Keywords: django,ophix,documentation,admin,fleet management
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ophix-server-base>=2026.06.08.01
+Requires-Dist: markdown>=3.4
+Requires-Dist: python-frontmatter>=1.0
+Requires-Dist: pygments>=2.19.2
+
+# ophix-docs
+
+**Documentation that lives where you actually need it** — searchable, in-admin docs for every [Ophix](https://ophix.io) server.
+
+Nobody wants to tab away from the admin panel to some separate wiki or GitHub page just to remember how a feature works — and that external doc is never quite sure which version you're actually running anyway. Every installed Ophix package ships its own docs pages; `ophix-docs` makes them available right alongside the data they describe, always matching whatever's actually installed.
+
+---
+
+## Installation
+
+```bash
+pip install ophix-docs
+```
+
+---
+
+## How it works
+
+Each Ophix package that ships documentation contains a `docs/` directory with:
+
+- One or more `.md` files with YAML front matter (`title`, `slug`, `order`, `section`)
+- A `sections.yaml` file declaring the section names used by those pages
+
+Documentation is **not loaded automatically on install** — it must be imported into the
+database with `update_docs`. If you used `run_install` to deploy your server,
+this was done for you. After upgrading packages, re-run the command to pick up any
+new or updated pages.
+
+---
+
+## Loading documentation
+
+### Automatic — via `run_install`
+
+If `ophix-docs` is installed when you run `ophix-manage run_install`, documentation
+is discovered and loaded automatically for all installed packages that ship docs.
+No further action is needed for a fresh install.
+
+### Manual — after upgrades or adding packages
+
+Discover which installed packages have docs:
+
+```bash
+ophix-manage list_docs_sources
+```
+
+Then load them. Use the Python module names (underscores, not hyphens), not pip
+package names. Include all relevant modules for your server type:
+
+**Credential server:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_creds,ophix_docs
+```
+
+**Configuration server:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_confs,ophix_docs
+```
+
+**Certificate server:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_certs,ophix_docs
+```
+
+**Certificate server with in-admin CA:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_certs,ophix_certs_ca,ophix_docs
+```
+
+**Zone server:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_zones,ophix_docs
+```
+
+The command is idempotent — safe to re-run at any time. It only creates and updates;
+it never deletes pages.
+
+---
+
+## Management commands
+
+### `list_docs_sources`
+
+List all installed apps that contain valid Ophix docs (a `docs/` directory with
+`.md` files and a `sections.yaml`).
+
+```bash
+ophix-manage list_docs_sources
+```
+
+Use `--json` for machine-readable output:
+
+```bash
+ophix-manage list_docs_sources --json
+```
+
+This is the recommended starting point after installing or upgrading packages — run
+it to confirm which app names to pass to `--include-app-docs`.
+
+---
+
+### `update_docs`
+
+Import and update documentation pages from installed app docs directories.
+Creates new pages and updates existing ones. Never deletes.
+
+```bash
+ophix-manage update_docs --include-app-docs <comma-separated module names>
+```
+
+**Options:**
+
+| Option | Description |
+| --- | --- |
+| `--include-app-docs <apps>` | Comma-separated list of app module names to import docs from |
+| `--path <dir>` | Additional docs directory to import (defaults to `BASE_DIR/docs` if it exists) |
+| `--language <code>` | Language code for translated docs — omit for default language |
+
+---
+
+### `purge_docs`
+
+Remove documentation pages from the database.
+
+```bash
+# Remove specific pages by slug
+ophix-manage purge_docs my-slug another-slug
+
+# Remove all pages for the default language
+ophix-manage purge_docs --all
+
+# Remove pages whose source files no longer exist on disk
+ophix-manage purge_docs --deleted
+
+# Preview without deleting
+ophix-manage purge_docs --all --dry-run
+ophix-manage purge_docs --deleted --dry-run
+```
+
+**Options:**
+
+| Option | Description |
+| --- | --- |
+| `--all` | Delete all pages for the selected language |
+| `--deleted` | Delete pages whose source file has been removed from disk |
+| `--language <code>` | Restrict to a specific language (defaults to default language) |
+| `--dry-run` | Preview what would be deleted without deleting anything |
+
+---
+
+### `export_docs`
+
+Export documentation pages from the database back to markdown files. Useful for
+backing up custom docs or extracting pages for translation.
+
+```bash
+ophix-manage export_docs --output-dir /path/to/export/
+```
+
+**Options:**
+
+| Option | Description |
+| --- | --- |
+| `--output-dir <dir>` | Directory to write exported `.md` files and `sections.yaml` (required) |
+| `--language <code>` | Language to export (defaults to the server's `LANGUAGE_CODE`) |
+
+---
+
+## Language packs
+
+Translated documentation ships as separate pip packages
+(`ophix-lang-fr-creds`, `ophix-lang-fr-confs`, etc.). Install the pack and import
+with `--language`:
+
+```bash
+pip install ophix-lang-fr-creds
+ophix-manage update_docs --include-app-docs ophix_lang_fr_creds --language fr
+```
+
+---
+
+## Writing custom docs
+
+Any markdown file placed in a `docs/` directory of an installed Django app can be
+imported by `update_docs`. Each file requires YAML front matter:
+
+```yaml
+---
+title: My Page Title
+slug: my-page-slug
+order: 10
+section: My Section
+---
+
+Page content here...
+```
+
+The `sections.yaml` in the same directory must declare any sections used:
+
+```yaml
+sections:
+  - name: My Section
+    collapsed: false
+```

ophix_docs-2026.10.4.1/README.md

@@ -0,0 +1,209 @@
+# ophix-docs
+
+**Documentation that lives where you actually need it** — searchable, in-admin docs for every [Ophix](https://ophix.io) server.
+
+Nobody wants to tab away from the admin panel to some separate wiki or GitHub page just to remember how a feature works — and that external doc is never quite sure which version you're actually running anyway. Every installed Ophix package ships its own docs pages; `ophix-docs` makes them available right alongside the data they describe, always matching whatever's actually installed.
+
+---
+
+## Installation
+
+```bash
+pip install ophix-docs
+```
+
+---
+
+## How it works
+
+Each Ophix package that ships documentation contains a `docs/` directory with:
+
+- One or more `.md` files with YAML front matter (`title`, `slug`, `order`, `section`)
+- A `sections.yaml` file declaring the section names used by those pages
+
+Documentation is **not loaded automatically on install** — it must be imported into the
+database with `update_docs`. If you used `run_install` to deploy your server,
+this was done for you. After upgrading packages, re-run the command to pick up any
+new or updated pages.
+
+---
+
+## Loading documentation
+
+### Automatic — via `run_install`
+
+If `ophix-docs` is installed when you run `ophix-manage run_install`, documentation
+is discovered and loaded automatically for all installed packages that ship docs.
+No further action is needed for a fresh install.
+
+### Manual — after upgrades or adding packages
+
+Discover which installed packages have docs:
+
+```bash
+ophix-manage list_docs_sources
+```
+
+Then load them. Use the Python module names (underscores, not hyphens), not pip
+package names. Include all relevant modules for your server type:
+
+**Credential server:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_creds,ophix_docs
+```
+
+**Configuration server:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_confs,ophix_docs
+```
+
+**Certificate server:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_certs,ophix_docs
+```
+
+**Certificate server with in-admin CA:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_certs,ophix_certs_ca,ophix_docs
+```
+
+**Zone server:**
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_zones,ophix_docs
+```
+
+The command is idempotent — safe to re-run at any time. It only creates and updates;
+it never deletes pages.
+
+---
+
+## Management commands
+
+### `list_docs_sources`
+
+List all installed apps that contain valid Ophix docs (a `docs/` directory with
+`.md` files and a `sections.yaml`).
+
+```bash
+ophix-manage list_docs_sources
+```
+
+Use `--json` for machine-readable output:
+
+```bash
+ophix-manage list_docs_sources --json
+```
+
+This is the recommended starting point after installing or upgrading packages — run
+it to confirm which app names to pass to `--include-app-docs`.
+
+---
+
+### `update_docs`
+
+Import and update documentation pages from installed app docs directories.
+Creates new pages and updates existing ones. Never deletes.
+
+```bash
+ophix-manage update_docs --include-app-docs <comma-separated module names>
+```
+
+**Options:**
+
+| Option | Description |
+| --- | --- |
+| `--include-app-docs <apps>` | Comma-separated list of app module names to import docs from |
+| `--path <dir>` | Additional docs directory to import (defaults to `BASE_DIR/docs` if it exists) |
+| `--language <code>` | Language code for translated docs — omit for default language |
+
+---
+
+### `purge_docs`
+
+Remove documentation pages from the database.
+
+```bash
+# Remove specific pages by slug
+ophix-manage purge_docs my-slug another-slug
+
+# Remove all pages for the default language
+ophix-manage purge_docs --all
+
+# Remove pages whose source files no longer exist on disk
+ophix-manage purge_docs --deleted
+
+# Preview without deleting
+ophix-manage purge_docs --all --dry-run
+ophix-manage purge_docs --deleted --dry-run
+```
+
+**Options:**
+
+| Option | Description |
+| --- | --- |
+| `--all` | Delete all pages for the selected language |
+| `--deleted` | Delete pages whose source file has been removed from disk |
+| `--language <code>` | Restrict to a specific language (defaults to default language) |
+| `--dry-run` | Preview what would be deleted without deleting anything |
+
+---
+
+### `export_docs`
+
+Export documentation pages from the database back to markdown files. Useful for
+backing up custom docs or extracting pages for translation.
+
+```bash
+ophix-manage export_docs --output-dir /path/to/export/
+```
+
+**Options:**
+
+| Option | Description |
+| --- | --- |
+| `--output-dir <dir>` | Directory to write exported `.md` files and `sections.yaml` (required) |
+| `--language <code>` | Language to export (defaults to the server's `LANGUAGE_CODE`) |
+
+---
+
+## Language packs
+
+Translated documentation ships as separate pip packages
+(`ophix-lang-fr-creds`, `ophix-lang-fr-confs`, etc.). Install the pack and import
+with `--language`:
+
+```bash
+pip install ophix-lang-fr-creds
+ophix-manage update_docs --include-app-docs ophix_lang_fr_creds --language fr
+```
+
+---
+
+## Writing custom docs
+
+Any markdown file placed in a `docs/` directory of an installed Django app can be
+imported by `update_docs`. Each file requires YAML front matter:
+
+```yaml
+---
+title: My Page Title
+slug: my-page-slug
+order: 10
+section: My Section
+---
+
+Page content here...
+```
+
+The `sections.yaml` in the same directory must declare any sections used:
+
+```yaml
+sections:
+  - name: My Section
+    collapsed: false
+```

ophix_docs-2026.10.4.1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ophix-docs"
+version = "2026.10.04.01"
+description = "Inline markdown documentation plugin for Ophix fleet management servers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name = "Ophix Project"}
+]
+keywords = ["django", "ophix", "documentation", "admin", "fleet management"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "ophix-server-base>=2026.06.08.01",
+    "markdown>=3.4",
+    "python-frontmatter>=1.0",
+    "pygments>=2.19.2"
+]
+
+[project.urls]
+Homepage = "https://ophix.io"
+Documentation = "https://github.com/ophixproject/ophix-docs#readme"
+Source = "https://github.com/ophixproject/ophix-docs"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ophix_docs = [
+    "OPHIX_RELEASE_NOTES.md",
+    "templates/**/*.html",
+    "static/**/*",
+    "docs/**/*",
+    "locale/**/*",
+    "deploy_templates/**/*",
+]
+
+[project.entry-points."ophix.plugins"]
+ophix_docs = "ophix_docs"

ophix_docs-2026.10.4.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ophix_docs-2026.10.4.1/src/ophix_docs/OPHIX_RELEASE_NOTES.md

@@ -0,0 +1,110 @@
+# Ophix Docs Release Notes
+
+## 2026.10.04.01
+
+- Reworked `README.md`'s opening with a hook-first pitch — docs that live where you actually
+  need them, right alongside the data they describe — as part of the 16-package
+  taskserver-release-wave README overhaul.
+
+## 2026.09.26.02
+
+- i18n regression check: the `"General"` fallback section label shown in the admin Table of Contents when a page has no `section` set was unwrapped. Wrapped in `gettext_lazy`.
+
+## 2026.09.26.01
+
+- Verified real compatibility under Python 3.14 (not just added the classifier) as part of the taskserver-release-wave compatibility sweep, and added `Programming Language :: Python :: 3.14` to the package classifiers.
+
+## 2026.08.30.01
+
+- Table of Contents (docpage changelist): removed the `font-size` overrides on
+  `.doc-anchor-link` (0.875em) and `.doc-anchor-link.level-3` (0.83em) so page titles
+  and every level of anchor sub-item render at the same, standard body font size.
+  Indentation and opacity are still used to convey nesting depth.
+
+## 2026.05.30.09
+
+- Search snippet stripping now also handles markdown tables: separator rows (`| --- |`)
+  are removed entirely and content rows have their pipe delimiters stripped, leaving
+  just the cell values as readable text.
+
+## 2026.05.30.08
+
+- Search snippets are now stripped of markdown syntax before display — headings, bold,
+  italic, code fences, links, list markers, and blockquotes are all removed, leaving
+  clean readable plain text. The monospace/pre-wrap styling on snippets is removed accordingly.
+
+## 2026.05.30.07
+
+- Search V2: results now link to the specific section (h2/h3) within a page that
+  contains the match, with `?q=` forwarded so the page highlights all occurrences.
+- Doc page view: when opened via a search result link, all occurrences of the search
+  term are highlighted with `<mark>` (skipping code blocks). Scrolls to the first
+  match automatically if no anchor is present in the URL.
+
+## 2026.05.30.06
+
+- Page name hover in docs index now uses the generic link hover colour, consistent
+  with anchor sub-link colours.
+
+## 2026.05.30.05
+
+- Fix section collapsed/expanded state not persisting: switched from sessionStorage
+  to localStorage, and fixed restore logic to correctly re-expand sections that were
+  collapsed by default but expanded by the user.
+
+## 2026.05.30.04
+
+- Renamed "Pages" to "Contents" in sidebar; docs index heading changed to "Table
+  of Contents".
+- Page links in docs index are now collapsible; h2/h3 anchors appear as sub-links
+  under each page. Anchors extracted and stored by update_docs (run after upgrade).
+- Added "Search" entry in sidebar: full-text search across page titles and content.
+- Dark mode: h1/h2 headings in doc pages now lighten with the same per-theme accent
+  lightness setting as links.
+- "Back to Index" renamed to "Back to Contents".
+
+## 2026.05.30.03
+
+- Docs index section headings and toggle buttons now lighten in dark mode using the
+  same per-theme accent lightness setting as generic links.
+
+## 2026.05.30.02
+
+- Fix docs index bullets: replaced ul/li with div elements to prevent Django admin
+  base CSS from applying list-style to page link rows.
+
+## 2026.05.30.01
+
+- Docs index restyled to match token policy visual quality: collapsible sections
+  with header bar, page count, hover left-border accent, dark mode aware.
+- Highlight.js theme now switches on Django admin dark mode toggle (data-theme
+  attribute) rather than OS prefers-color-scheme media query.
+
+## 2026.05.27.03
+
+- Doc page headings (h1/h2) now use the theme module color; h3/h4 use the generic link color.
+
+## 2026.05.27.02
+
+- Docs section headings now use the theme module color to match arrows and bullets.
+
+## 2026.05.27.01
+
+- Docs tree arrows and bullet markers now use the theme module color
+  (`--admin-interface-module-background-color`) instead of the browser default,
+  so they match the active theme across all colour schemes.
+
+## 2026.05.22.02
+
+- Added migration 0009: `DocPage.source_path` help text updated to reference
+  `update_docs` (was `ophix_docs_update`).
+
+## 2026.05.22.01
+
+- Management commands renamed for consistency with `ophix-manage` context:
+  `ophix_docs_update` → `update_docs`, `ophix_docs_purge` → `purge_docs`,
+  `ophix_docs_export` → `export_docs`, `ophix_docs_list_sources` → `list_docs_sources`.
+
+## 2026.05.01.02
+
+- Added `OPHIX_RELEASE_NOTES.md` for release notes delivery.

ophix_docs-2026.10.4.1/src/ophix_docs/__init__.py

@@ -0,0 +1,4 @@
+plugin_category = "addon"
+plugin_sort = 210
+
+default_app_config = "ophix_docs.apps.OphixDocsConfig"

ophix_docs-2026.10.4.1/src/ophix_docs/_version.py

@@ -0,0 +1,2 @@
+__version__ = "2026.10.04.01"
+__package_name__ = "ophix-docs"