docs: auto-generated API reference site; remove stale docs (#259) - #308
Open
alecjacobson wants to merge 4 commits into
Open
docs: auto-generated API reference site; remove stale docs (#259)#308alecjacobson wants to merge 4 commits into
alecjacobson wants to merge 4 commits into
Conversation
The old documentation was scraped from the *pybind11* era module via pydoc
(tutorial/igl_docs.md, tutorial/exporter.py) and the tutorials mirrored the C++
tutorial and rendered with the unmaintained meshplot — all long stale, and
nothing in CI ever deployed them. Remove them entirely.
Replace with a Material-for-MkDocs site whose API reference is generated
directly from the compiled bindings' .pyi type stubs, so it always matches what
is actually bound:
- website/generate_api.py parses the nanobind stubs with ast (tolerant of the
invalid signatures nanobind occasionally emits), renders compact signatures
(e.g. float64[m, n]) and doxygen-style docstrings, and cross-links every
function that has a C++ counterpart to its page on libigl.github.io/dox.
- website/mkdocs.yml + landing/install pages, on the same Material stack as
libigl.github.io so this can lift-and-shift into that unified site as a
/python/ subtree (per-function C++<->Python cross-links already in place).
- .github/workflows/docs.yml builds the site on every PR and deploys a preview
to gh-pages on main, so it can no longer silently rot.
Generated pages (website/docs/api) and the built site are gitignored; CI
regenerates them. The old contributing guide moves under website/docs.
Also fixes a real binding bug surfaced by the generator: circumradius's first
argument was bound with an empty name (""_a), so it couldn't be passed by
keyword and produced an invalid stub; it is now "V"_a.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two table-of-contents bugs on the generated API pages:
- libigl's '#V'/'#E'/'#F' ("number of") notation in docstrings was parsed as
space-less Markdown ATX headings (python-markdown accepts '#heading'),
injecting stray <h1> entries that polluted the TOC and broke Material's
nested rendering so the sidebar TOC truncated partway (around 'edges').
Escape a leading '#' in rendered docstring text.
- The C++ Doxygen cross-link sat inside each function heading, so its text and
emoji leaked into every TOC entry and the heading anchor slug. Move it to a
standalone chip line below the heading; cap toc_depth at 3.
The API TOC now lists all functions/classes and no longer shows 'C++'.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The generated C++ links used the wrong Doxygen file-page names and pointed at non-existent pages: - Doxygen mangles output filenames: '.h' -> '_8h' and every underscore is doubled (marching_cubes.h -> marching__cubes_8h.html). Case is preserved (AABB.h -> AABB_8h.html). The generator was using single underscores, so most multi-word links 404'd. - Names that exist in more than one header (e.g. marching_cubes in igl/ and igl/copyleft/) get disambiguated by Doxygen into non-derivable names; only link names whose header is unique in the tree. - The deployed /dox/ can lag the bindings' libigl version (new/renamed headers), so validate every derived link against the actual Doxygen page list (--dox-index, the site's files.html) and drop any that don't exist. Result: no 404s. CI fetches files.html and passes it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The :material-language-cpp: icon is itself a C++ logo, so the chip read 'C++ C++ reference'. Keep just the 'C++ reference' text. (Matches the same fix in the libigl.github.io site copy.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overhauls the Python-bindings documentation. This is Phase 1 of the unified-site plan (Option B): a self-contained, always-current Python docs site, built on the same Material-for-MkDocs stack as
libigl.github.ioso it can lift-and-shift into that site as a/python/subtree.The problem
tutorial/igl_docs.mdwas scraped from the old pybind11 module viapydoc(tutorial/exporter.py) — dead names,>>>examples, wrong signatures.pip/wheels), so the site rots.What this does
Removes all of it:
tutorial/(notebooks,igl_docs.md,exporter.py, helpers, 77 legacy images) and the old rootmkdocs.yml.Adds a generated site under
website/:generate_api.py— parses the compiled bindings'.pyitype stubs withast(the reliable signature source for nanobind; tolerant of the invalid signatures nanobind occasionally emits). Renders compact signatures (float64[m, n]), formats doxygen@param/@returndocstrings, and cross-links every function with a C++ counterpart to its Doxygen page atlibigl.github.io/dox/(~196/221 core functions link today).mkdocs.yml+ landing/install pages on Material, matchinglibigl.github.ioconventions (content tabs, MathJax, emoji icons) so unification is a lift-and-shift..github/workflows/docs.yml— builds the site on every PR (mkdocs build --strict) and deploys a preview togh-pagesonmain. The docs can no longer silently rot.Generated pages (
website/docs/api/) and the builtsite/are gitignored; CI regenerates them from the installed package.Also: a real binding bug
The generator surfaced that
circumradius's first argument was bound with an empty name (""_a) — so it couldn't be passed by keyword and produced an invalid stub. Fixed to"V"_a.Scope note
Per discussion, the tutorial example rewrite is deprioritized (polyscope-based examples can come later, organized as snippets). This PR focuses on the API reference + killing the rot. Phase 2 (wiring this into
libigl/libigl.github.ioas/python/with reciprocal C++→Python links) is a follow-up in that repo.Addresses #259.
🤖 Generated with Claude Code