opdoc 0.1.0__tar.gz

opdoc-0.1.0/LICENSE.TXT

@@ -0,0 +1,7 @@
+Copyright 2026 Meehai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

opdoc-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE.TXT
+include opdoc/*.css
+include opdoc/*.html.jinja2

opdoc-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: opdoc
+Version: 0.1.0
+Summary: Opinionated, self-contained pdoc documentation sites
+Home-page: https://gitlab.com/meehai/opdoc
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.TXT
+Requires-Dist: pdoc==16.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4; extra == "dev"
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# opdoc
+
+Opinionated, self-contained [pdoc](https://pdoc.dev/) documentation sites. One command turns a
+project's `docs/` directory plus its `README.md` into a themed static site with prose pages, API
+reference, client-side search, and no config file.
+
+```bash
+opdoc docs/ public
+```
+
+`DOCS` is required; `OUT` defaults to `<project-root>/public`. The project root is the parent of
+`DOCS`, so `opdoc docs/` works from a normal checkout.
+
+## What a project supplies
+
+```
+project/
+├── README.md                    home page (rendered as guide.html)
+├── docs/
+│   ├── custom.css               optional project CSS, appended after opdoc's base style
+│   ├── source/**/*.md           prose pages; the directory tree is the "Pages" sidebar
+│   └── scripts/*.py             optional build-time page generators
+└── <packages>/                  auto-detected API roots
+```
+
+That is the whole contract. Theme, template, search, link rewriting, and the pdoc pin live in
+opdoc.
+
+## API pages
+
+Without flags, opdoc documents every top-level package directory (a directory with `__init__.py`),
+skipping `docs/`, `test/`, `examples/`, `pkg/`, `build/`, `dist/`, and `public/`. Each package's
+re-exports are blanked in memory by default, so a class is documented once on its own module page.
+
+For a `src/` layout, namespace packages, or a subset of packages, pass `--api-package` and the
+matching import roots:
+
+```bash
+opdoc docs/ public \
+  --api-package src/robolib \
+  --api-package src/robosim \
+  --import-path src \
+  --import-path .
+```
+
+`--keep-reexports` leaves `__all__` alone when a package landing page should show its re-exports.
+
+## Scripts
+
+Every non-underscore `docs/scripts/*.py` is imported before `docs/source` is scanned. It must
+define:
+
+```python
+def generate(site):
+    text, _missing = build_the_page()
+    site.write_page("3. Reference/generated.md", text)
+```
+
+`site.write_page(relative_path, text)` writes a markdown page below `docs/source`; the normal scan
+then renders it to HTML. `site.root`, `site.docs`, and `site.out` are absolute paths. Scripts run
+in filename order. `_`-prefixed files are helpers and are not run.
+
+Scripts can import project code: `--import-path` entries are already on `sys.path` and in
+`PYTHONPATH`. The scripts directory is on `sys.path` too, so a script may `import _helper` from a
+sibling `_`-prefixed file.
+
+## Pages menu
+
+`docs/source/` is the sidebar:
+
+- every `*.md` is a page; the title is its first `# ` heading (fallback: file name);
+- a directory is a collapsible group; `index.md` makes the group itself a page;
+- a leading number sorts first and numerically (`1. Examples`, `2. Architecture`);
+- `_`-prefixed files/dirs are drafts; a top-level `README.md` is ignored (the repo README is home);
+- names that slugify to the same module are an error.
+
+Links in `README.md` and pages stay repo-relative. opdoc rewrites `*.md` links to the generated
+pages, copies referenced images, and sends other repo paths to GitLab blob/tree URLs. Set
+`--repo-slug owner/project` and `--repo-branch branch` when the git remote does not describe the
+published repo (for example, a vendored checkout).
+
+## Vendored sites
+
+`--vendored NAME` adds `vendored/NAME/index.html` to the sidebar. It does **not** build that site;
+an orchestrating project script builds each `pkg/NAME/docs` into `OUT/vendored/NAME/` with the same
+tool. This keeps every site self-contained and avoids module collisions between projects.
+
+## Install
+
+```bash
+pip install opdoc
+```
+
+opdoc pins the pdoc version it is tested against (`pdoc==16.0.0`) because it drives pdoc's render
+API directly. Python 3.12+.
+
+For development:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest test/
+python -m opdoc docs/ public
+```
+
+## Tests
+
+- `test/unit/` exercises the pure helpers (slugging, ordering, source scanning, script loading,
+  path guards).
+- `test/integration/` builds a real fixture site with pdoc and checks the home page, API pages,
+  generated script page, sidebar, rewritten links, assets, and CSS.

opdoc-0.1.0/README.md

@@ -0,0 +1,111 @@
+# opdoc
+
+Opinionated, self-contained [pdoc](https://pdoc.dev/) documentation sites. One command turns a
+project's `docs/` directory plus its `README.md` into a themed static site with prose pages, API
+reference, client-side search, and no config file.
+
+```bash
+opdoc docs/ public
+```
+
+`DOCS` is required; `OUT` defaults to `<project-root>/public`. The project root is the parent of
+`DOCS`, so `opdoc docs/` works from a normal checkout.
+
+## What a project supplies
+
+```
+project/
+├── README.md                    home page (rendered as guide.html)
+├── docs/
+│   ├── custom.css               optional project CSS, appended after opdoc's base style
+│   ├── source/**/*.md           prose pages; the directory tree is the "Pages" sidebar
+│   └── scripts/*.py             optional build-time page generators
+└── <packages>/                  auto-detected API roots
+```
+
+That is the whole contract. Theme, template, search, link rewriting, and the pdoc pin live in
+opdoc.
+
+## API pages
+
+Without flags, opdoc documents every top-level package directory (a directory with `__init__.py`),
+skipping `docs/`, `test/`, `examples/`, `pkg/`, `build/`, `dist/`, and `public/`. Each package's
+re-exports are blanked in memory by default, so a class is documented once on its own module page.
+
+For a `src/` layout, namespace packages, or a subset of packages, pass `--api-package` and the
+matching import roots:
+
+```bash
+opdoc docs/ public \
+  --api-package src/robolib \
+  --api-package src/robosim \
+  --import-path src \
+  --import-path .
+```
+
+`--keep-reexports` leaves `__all__` alone when a package landing page should show its re-exports.
+
+## Scripts
+
+Every non-underscore `docs/scripts/*.py` is imported before `docs/source` is scanned. It must
+define:
+
+```python
+def generate(site):
+    text, _missing = build_the_page()
+    site.write_page("3. Reference/generated.md", text)
+```
+
+`site.write_page(relative_path, text)` writes a markdown page below `docs/source`; the normal scan
+then renders it to HTML. `site.root`, `site.docs`, and `site.out` are absolute paths. Scripts run
+in filename order. `_`-prefixed files are helpers and are not run.
+
+Scripts can import project code: `--import-path` entries are already on `sys.path` and in
+`PYTHONPATH`. The scripts directory is on `sys.path` too, so a script may `import _helper` from a
+sibling `_`-prefixed file.
+
+## Pages menu
+
+`docs/source/` is the sidebar:
+
+- every `*.md` is a page; the title is its first `# ` heading (fallback: file name);
+- a directory is a collapsible group; `index.md` makes the group itself a page;
+- a leading number sorts first and numerically (`1. Examples`, `2. Architecture`);
+- `_`-prefixed files/dirs are drafts; a top-level `README.md` is ignored (the repo README is home);
+- names that slugify to the same module are an error.
+
+Links in `README.md` and pages stay repo-relative. opdoc rewrites `*.md` links to the generated
+pages, copies referenced images, and sends other repo paths to GitLab blob/tree URLs. Set
+`--repo-slug owner/project` and `--repo-branch branch` when the git remote does not describe the
+published repo (for example, a vendored checkout).
+
+## Vendored sites
+
+`--vendored NAME` adds `vendored/NAME/index.html` to the sidebar. It does **not** build that site;
+an orchestrating project script builds each `pkg/NAME/docs` into `OUT/vendored/NAME/` with the same
+tool. This keeps every site self-contained and avoids module collisions between projects.
+
+## Install
+
+```bash
+pip install opdoc
+```
+
+opdoc pins the pdoc version it is tested against (`pdoc==16.0.0`) because it drives pdoc's render
+API directly. Python 3.12+.
+
+For development:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest test/
+python -m opdoc docs/ public
+```
+
+## Tests
+
+- `test/unit/` exercises the pure helpers (slugging, ordering, source scanning, script loading,
+  path guards).
+- `test/integration/` builds a real fixture site with pdoc and checks the home page, API pages,
+  generated script page, sidebar, rewritten links, assets, and CSS.

opdoc-0.1.0/opdoc/__init__.py

@@ -0,0 +1,4 @@
+"""opdoc -- opinionated pdoc docs generator."""
+from opdoc.opdoc import Site, build_site, main
+
+__all__ = ["Site", "build_site", "main"]

opdoc-0.1.0/opdoc/__main__.py

@@ -0,0 +1,4 @@
+from opdoc.opdoc import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

opdoc-0.1.0/opdoc/base.css

@@ -0,0 +1,391 @@
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+}
+
+.pdoc .il {
+  color: #131416;
+}
+
+nav.pdoc a.pdoc-button.module-list-button {
+  display: none;
+}
+
+.pdoc .modulename a:hover {
+  color: whitesmoke;
+}
+
+.pdoc .classattr {
+  color: #fff;
+}
+
+.pdoc .docstring .pdoc-code {
+  background-color: #232627;
+}
+
+.pdoc pre {
+  width: fit-content;
+}
+
+.pdoc pre a {
+  color: whitesmoke;
+}
+
+.pdoc pre a:hover {
+  color: #676767;
+}
+
+
+/* Submodules and API Doc. */
+
+.pdoc h2 {
+  color: #fff;
+  font-weight: 0;
+  margin: 0.3em 0;
+  padding: 0.2em 0;
+  content: "Module Content";
+}
+
+/* header */
+.pdoc h5 {
+  color: white;
+  font-style: italic;
+}
+
+/* Module name */
+
+.pdoc .modulename {
+  color: #fff;
+  font-weight: 0;
+}
+
+.pdoc-code .ow {
+  color: var(--red);
+}
+
+nav.pdoc a.function {
+  color: var(--purple);
+}
+
+nav.pdoc a.function:hover {
+  background-color: var(--dark);
+}
+
+nav.pdoc .function::after {
+  content: "";
+}
+
+nav.pdoc .function::before {
+  content: "fn ";
+  color: var(--red);
+}
+
+nav.pdoc a.class {
+  color: whitesmoke;
+}
+
+/* Before the class name. This adds "class 'className'". */
+nav.pdoc .class::before {
+  content: "class ";
+  color: var(--red);
+}
+
+/* After the class name. This will remove `()` That comes after the class name. */
+nav.pdoc .class::after {
+  content: "";
+}
+
+nav.pdoc a.class:hover {
+  color: #fff;
+  background-color: var(--dark);
+}
+
+nav.pdoc a.variable {
+  color: whitesmoke;
+}
+
+/* Adds "var varname" to class variables. */
+nav.pdoc a.variable::before {
+  content: "var ";
+  color: #9d9d9d;
+  color: var(--red);
+}
+
+nav.pdoc a.variable:hover {
+  color: #fff;
+  background-color: var(--dark);
+}
+
+/* nav modules */
+nav.pdoc li a {
+  color: var(--purple);
+}
+
+nav.pdoc li a:hover {
+  background-color: var(--dark);
+}
+
+/* Assigned values */
+.pdoc span.default_value {
+  color: var(--lightblue);
+}
+
+.pdoc span.def {
+  font-weight: normal;
+  color: var(--red);
+}
+
+/*
+Attributes
+----------
+*/
+.pdoc h6#attributes {
+  color: #fff;
+  font-size: 25px;
+}
+
+/*
+Example
+-------
+*/
+
+.pdoc h6#example {
+  color: #fff;
+  font-size: 29px;
+}
+
+/*
+Notes
+-----
+*/
+
+.pdoc h6#notes {
+  font-size: 27px;
+  color: var(--orange);
+}
+
+/*
+Returns
+-------
+*/
+
+.pdoc h6#returns {
+  font-size: 27px;
+  color: white;
+}
+
+/*
+Parameters
+----------
+*/
+
+.pdoc h6#parameters {
+  font-size: 27px;
+  color: white;
+}
+
+/*
+Raises
+------
+*/
+
+.pdoc h6#raises {
+  font-size: 27px;
+  color: rgb(218, 55, 55);
+}
+
+/* False, True, None */
+
+.pdoc .kc {
+  color: var(--lightblue);
+}
+
+.pdoc li {
+  color: white;
+}
+
+/* Decorator module */
+
+.pdoc .nd {
+  color: var(--lightblue);
+}
+
+/* markdown **bold** -- genuinely bold + bright white so it stands out (e.g. the benchmark
+   win-markers on the Benchmarks page); was font-weight:normal, which made bold invisible */
+.pdoc b,
+strong {
+  color: #fff;
+  font-weight: 800;
+}
+
+/* markdown *emphasis* -- a plain italic that inherits the body color/size so it blends into the prose
+   instead of shouting. (Admonitions are styled separately, via .pdoc-alert-note / -warning below.) */
+
+.pdoc em {
+  font-style: italic;
+}
+
+/* Decorator color */
+
+.pdoc div.decorator {
+  color: var(--lightblue);
+}
+
+div.pdoc-code.codehilite {
+  background-color: var(--code);
+}
+
+/* class / function names */
+
+.pdoc span.name {
+  color: var(--purple);
+  font-weight: normal;
+}
+
+/* Inherited class name color */
+
+.pdoc span.base {
+  color: whitesmoke;
+}
+
+/* Before inherited members colors, i.e., "builtins." */
+
+.pdoc .inherited dt,
+.pdoc .inherited dt::before {
+  color: var(--silver);
+}
+
+
+/* Commas that separates parameters "," color */
+.pdoc .inherited dd:not(:last-child)::after {
+  color: #fff;
+}
+
+/* Commas that separates parameters "," color */
+
+.pdoc .inherited dd:not(:last-child)::after {
+  color: #fff;
+}
+
+/* Contents, Submodules, API Documentations */
+/* This also can be separated */
+.pdoc h1,
+.pdoc h2,
+.pdoc h3 {
+  font-weight: 300;
+  margin: 0.3em 0;
+  padding: 0.2em 0;
+  color: white;
+}
+
+/* Top left nav button */
+nav.pdoc .module-list-button {
+  display: inline-flex;
+  align-items: center;
+  margin-bottom: 1rem;
+  color: white;
+  border-color: white;
+}
+
+nav.pdoc .module-list-button:hover {
+  border-color: white;
+  color: white;
+}
+
+.pdoc pdoc-alert pdoc-alert-warning .p {
+  color: black;
+}
+
+.pdoc-code {
+  color: white;
+}
+
+.pdoc .pdoc-alert-warning {
+  color: black;
+  background-color: #d5a142;
+  border-color: black;
+}
+
+.pdoc .pdoc-alert-note {
+  color: rgb(7, 19, 24);
+  background-color: rgb(184, 231, 251) ;
+  border-color: var(--dark);
+}
+
+/* The nav bar */
+
+nav.pdoc {
+  background-color: rgb(55, 58, 72);
+}
+
+.pdoc-code .k {
+  color: var(--red);
+}
+
+/* === opdoc base overrides (per-project extras are appended from docs/custom.css) ========= */
+/* widen the content column (layout.css ships 54rem) by 1.5x so 120-char-wide code
+   examples render on a single line, without horizontal scrolling */
+main, header { width: calc(81rem + var(--sidebar-width)); }
+/* a Home link at the top of the sidebar, above search; styled like the "Modules"/"Contents" headings */
+nav.pdoc a.home-button { display: inline-block; color: #fff; font-weight: 300; font-size: 2rem; margin: 0.3em 0; }
+nav.pdoc a.home-button:hover { color: var(--lightblue); }
+/* README-heading primitives stay code in the body, but render as plain text in the sidebar menu */
+nav.pdoc code { font-family: inherit; background: none; color: inherit; padding: 0; border: 0; font-size: inherit; }
+/* prose/README images must never overflow the content column */
+.pdoc .docstring img { max-width: 100%; height: auto; }
+/* prose tables (e.g. the Benchmarks page): pdoc's default has no visible borders. Make them
+   full-width + "schematic" (crisp grid), with a header band and a subtle per-row hover shade. */
+.pdoc .docstring table {
+  display: table; width: 100%; max-width: 100%; table-layout: auto;  /* fully override pdoc's
+  block/max-content/overflow default so the table fills the content column instead of shrink-wrapping */
+  overflow: visible; border-collapse: collapse; margin: 1rem 0;
+}
+.pdoc .docstring th, .pdoc .docstring td {
+  border: 1px solid rgba(255, 255, 255, 0.22); padding: 0.4rem 0.6rem; text-align: left; vertical-align: top;
+}
+.pdoc .docstring thead th { background: var(--accent); font-weight: 600; }
+.pdoc .docstring tbody tr:hover { background: rgba(255, 255, 255, 0.06); }
+/* Collapsible sidebar trees (Modules + the grouped nodes under Pages). Nodes that have
+   children are <details><summary>label</summary><ul>kids</ul></details>: collapsed by default, so
+   only the top level (microecs) shows; opening a node reveals its children, to any depth.
+   The path to the CURRENT page is emitted <details open>, so you always see where you are. Both
+   trees carry class="nav-tree". */
+nav.pdoc > div > ul.nav-tree { margin-left: 0; }               /* cancel pdoc's negative root margin */
+/* the disclosure row: hide the browser's default triangle, draw our own ▸ that rotates to ▾ on open */
+nav.pdoc .nav-tree summary { list-style: none; cursor: pointer; padding: .2rem 0; }  /* match the
+  .2rem vertical rhythm of leaf link rows (nav.pdoc li a) so collapsible group rows aren't cramped */
+nav.pdoc .nav-tree summary::-webkit-details-marker { display: none; }
+nav.pdoc .nav-tree summary::before {
+  content: "\25B8"; display: inline-block; width: 1rem; color: var(--silver); transition: transform 100ms;
+}
+nav.pdoc .nav-tree details[open] > summary::before { transform: rotate(90deg); }
+/* a link/label inside a summary flows inline right after the marker (no block padding) */
+nav.pdoc .nav-tree summary a, nav.pdoc .nav-tree summary .tree-label { display: inline; padding-left: 0; }
+/* leaf rows have no marker -- pad them by the marker width so their text aligns with expandable siblings */
+nav.pdoc .nav-tree li > a { padding-left: 1rem; }
+/* namespace labels (Examples & Tutorials) are plain text, not links -- match the link color */
+nav.pdoc .tree-label { color: var(--purple); }
+/* indentation + rails: each nested <ul> indents once and draws a faint vertical rail spanning its
+   children; hovering a node lights its subtree's rail (and its ancestors') so the subtree stands out */
+nav.pdoc .nav-tree ul { padding-left: 0.6rem; border-left: 1px solid rgba(255, 255, 255, 0.18); }
+nav.pdoc .nav-tree details:hover > ul { border-left-color: var(--lightblue); }
+/* indent the "Current Page" ToC one tab under its heading, matching the Pages/Modules trees (the H1
+   title is now in the heading, so its sub-sections would otherwise sit flush against the left edge) */
+nav.pdoc > div > ul.page-toc { margin-left: 0; }
+nav.pdoc .page-toc li a { padding-left: 1rem; }
+/* Expandable prose code blocks: a long fenced example starts clamped to a few lines with a fade-out and
+   a "Show more" toggle, so a page isn't one wall of code. Short blocks stay fully open (the JS removes
+   the clamp when a block doesn't actually overflow). Scoped to .docstring, so the API "View Source"
+   dropdowns keep their own separate toggle. */
+.pdoc .docstring .pdoc-code.collapsible { position: relative; }
+.pdoc .docstring .pdoc-code.collapsible.collapsed { max-height: 12em; overflow: hidden; }
+.pdoc .docstring .pdoc-code.collapsible.collapsed::after {
+  content: ""; position: absolute; left: 0; right: 0; bottom: 0; height: 3.5em; pointer-events: none;
+  background: linear-gradient(to bottom, rgba(35, 38, 39, 0), var(--code));
+}
+.pdoc .docstring .code-toggle {
+  display: block; width: fit-content; margin: 0.5rem 1em 1.25rem; padding: 0.25rem 0.7rem; cursor: pointer;
+  position: relative; z-index: 1;   /* sit above the position:relative code block, never behind it */
+  font: inherit; color: var(--lightblue); background: var(--code);
+  border: 1px solid rgba(255, 255, 255, 0.22); border-radius: 4px;
+}
+.pdoc .docstring .code-toggle:hover { color: #fff; border-color: var(--lightblue); }