[sub-issue #53] Docs

[emapuljak]

Sub-issue - Documentation overhaul (autodoc, docstrings, MyST) + docs-build gate in CI

Description

Make the documentation auto-generated from source and self-consistent, backfill docstrings so the API
reference is complete, standardize the docs on a single format (MyST Markdown), and add a build-only
docs check to CI. This is the third of three PRs (A → B → C) and depends on PR A (docs extra + the
docs/Makefile/.readthedocs.yaml/conf.py fixes) and PR B (the ci.yml this job plugs into).

Scope = sub-issue 5 (documentation overhaul).

✅ This is the PR that enables the Ruff D (docstring) rule. Turn it on together with the
docstring backfill so ruff check stays green — enabling it before the backfill would flood with
errors. Once on, CI blocks any new undocumented public symbol.

---

Tasks

1. API autodoc

• Wire up automatic API-reference generation from docstrings using the already-enabled sphinx.ext.autodoc + autosummary + napoleon (in docs/source/conf.py), replacing the hand-written tables in docs/source/reference.md (which drift from code).
• Confirm the sphinx-apidoc call points at ../src/pquant (fixed in PR A) and generates the API pages.

2. Docstring standardization + full coverage

• Standardize docstring style on Google (already the de-facto convention). Convert the one NumPy-style outlier src/pquant/core/torch/hgq_quantizer.py.
• Backfill docstrings so every public function/method/class has one (Args / Returns / Raises where applicable). Baseline ≈ 230 docstrings across ≈ 900 defs.
• Enable the Ruff D rule (add the D family back to select) — with the backfill complete, ruff check passes and future gaps are blocked.

3. Standardize docs on MyST Markdown

• Convert docs/source/index.rst → index.md using MyST's Markdown toctree directive so the entire docs tree is a single format.
• Narrow source_suffix to ['.md'] once no .rst remains.

4. Docs-build CI job

• Add a build-only docs job to ci.yml: pip install -e ".[docs]" → cd docs && make html with -W (warnings-as-errors), no deploy. Wire it into the ci-ok gate.
• Keep deploy in the separate (PR-A-fixed) sphinx-build.yml. Do not add doctest — runnable examples are covered by nbmake.

---

Acceptance Criteria

• The public API (layers, pruning methods, quantizers, …) is auto-documented via autodoc/autosummary/napoleon; reference.md no longer relies on hand-maintained API tables.
• sphinx-apidoc in docs/Makefile targets ../src/pquant.
• Docstring style is uniformly Google; hgq_quantizer.py is converted from NumPy style.
• The Ruff D rule is enabled and ruff check . passes — i.e. every public function/method/class is documented.
• Docs are single-format MyST Markdown: index.rst → index.md, and source_suffix = ['.md'].
• cd docs && make html builds successfully with .[docs] installed.
• A build-only docs job (make html -W, no deploy) is added to ci.yml and wired into the ci-ok gate.