Merge main into jg/pretty-minimal and resolve core.py conflicts

Author: james-golden-arcadia

.pre-commit-config.yaml

@@ -33,3 +33,9 @@ repos:
         entry: make typecheck
         language: system
         pass_filenames: false
+
+      - id: test
+        name: Test
+        entry: make test
+        language: system
+        pass_filenames: false

Makefile

@@ -12,8 +12,8 @@ lint:
 
 .PHONY: format
 format:
-	ruff check --fix .
 	ruff format .
+	ruff check --fix .
 
 .PHONY: typecheck
 typecheck:

README.md

@@ -1,233 +1,28 @@
-> [!WARNING]
-> This repo is public but under intense reconstruction and is **not ready for users**. Please check back soon!
+[![Documentation Status](https://readthedocs.org/projects/glass-box-umap/badge/?version=latest)](https://glass-box-umap.readthedocs.io/en/latest/?badge=latest)
+[![PyPI - Version](https://img.shields.io/pypi/v/glass-box-umap)](https://pypi.org/project/glass-box-umap/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/glass-box-umap)](https://pypi.org/project/glass-box-umap/)
+[![GitHub license](https://img.shields.io/github/license/Arcadia-Science/glass-box-umap)](https://github.com/Arcadia-Science/glass-box-umap/blob/main/LICENSE)
 
 # Glass Box UMAP
 
-This repo contains a Python package called `glass_box_umap`.
+Glass Box UMAP augments UMAP by computing exact feature contributions to the UMAP embedding.
 
-This package augments UMAP by computing exact feature contributions to the UMAP embedding.
+Standard UMAP produces embeddings but offers no insight into why points land where they do. Glass Box UMAP solves this by using a specially designed neural network that enables exact computation of feature contributions, and does so without approximations. The feature attributions are mathematically exact, validated to near machine precision.
 
-The publication for Glass Box UMAP can be found [here](https://arcadia-science.github.io/glass-box-umap-notebook-pub/).
+# Documentation
 
-## Installation
+<a href="https://glass-box-umap.readthedocs.io">
+  <img src="docs/_assets/rtd-badge.png" width="200" alt="rtd">
+</a>
 
-```bash
-# pip
-pip install glass-box-umap
+All resources are hosted at [https://glass-box-umap.readthedocs.io](https://glass-box-umap.readthedocs.io).
 
-# uv
-uv pip install glass-box-umap
-```
+**Quick links**:
 
-Find complete installation instructions at `docs/install.md`.
+1. [**Installation**](https://glass-box-umap.readthedocs.io/en/latest/getting_started/install.html)
+1. [Quickstart](https://glass-box-umap.readthedocs.io/en/latest/getting_started/quickstart.html)
+1. [Citation](https://glass-box-umap.readthedocs.io/en/latest/meta/citation.html)
 
-## Development
+# About
 
-### Environment setup
-
-We use [uv](https://docs.astral.sh/uv/) for dependency management and build tooling. First, install uv:
-
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
-
-Make sure uv is installed and available. Verify this by checking which version you have:
-
-```bash
-uv --version
-```
-
-Then install the project with development dependencies:
-
-```bash
-uv sync --group dev
-```
-
-To also install documentation dependencies:
-
-```bash
-uv sync --group dev --group docs
-```
-
-This creates a virtual environment in `.venv` and installs all dependencies. The package itself is automatically installed in editable mode (equivalent to `pip install -e .`).
-
-The easiest way to run code is to simply prefix commands with `uv run` (e.g., `uv run <YOUR_COMMAND>`). This executes the command inside the virtual environment automatically, so you don't need to activate it first.
-
-Alternatively, if you prefer a traditional workflow, or are running from a different directory, you can manually source the activation script:
-
-```bash
-source .venv/bin/activate
-```
-
-### Formatting and linting
-
-To format the code, use the following command:
-
-```bash
-make format
-```
-
-To run the lint checks and type checking, use the following command:
-
-```bash
-make lint
-```
-
-### Pre-commit hooks
-
-We use pre-commit to run formatting and lint checks before each commit. To install the pre-commit hooks, use the following command:
-
-```bash
-pre-commit install
-```
-
-To run the pre-commit checks manually, use the following command:
-
-```bash
-make pre-commit
-```
-
-### Testing
-
-We use `pytest` for testing. The tests are found in the `glass_box_umap/tests/` subpackage. To run the tests, use the following command:
-
-```bash
-make test
-```
-
-### Managing dependencies
-
-We use uv to manage dependencies. To add a new dependency:
-
-```bash
-uv add some-package
-```
-
-To add a new development dependency:
-
-```bash
-uv add --group dev some-dev-package
-```
-
-To update a dependency:
-
-```bash
-uv lock --upgrade-package some-package
-```
-
-Whenever you add or update a dependency, uv will automatically update both `pyproject.toml` and `uv.lock`. Make sure to commit changes to these files.
-
-### Documentation
-
-We use Sphinx for documentation with the [`furo` theme](https://github.com/pradyunsg/furo). We also use some Sphinx extensions (described below) to make the process of writing documentation easier.
-
-To build the docs, first install `pandoc`. On macOS, this can be done using `brew`:
-
-```
-brew install pandoc
-```
-
-Then, build the docs using the following command:
-
-```bash
-uv run make docs
-```
-
-Note: the `pandoc` dependency is only required by the `nbsphinx` extension. If this extension is removed, there is no need to install `pandoc`.
-
-#### sphinx-autoapi
-
-This extension generates API docs automatically from the docstrings in the source code. To do so, it requires that docstrings adhere to the Google or Numpy style. This style is described in the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html).
-
-#### napolean
-
-Rather than writing our docstrings in RST, we use this extension to convert Google and NumPy-style docstrings to RST at build time.
-
-#### myst-parser
-
-RST is complicated to write. This extension lets us write our docs in Markdown and then converts them to RST at build time.
-
-#### nbsphinx
-
-It is often convenient to write examples as Jupyter notebooks. This extension executes Jupyter notebooks and renders the results in the docs at build time. It requires `pandoc`, which can be installed using `brew install pandoc`.
-
-#### Removing unused Sphinx extensions
-
-To remove an unused extension, delete the corresponding line from the `extensions` list in `docs/conf.py` and delete the extension from the `docs` dependency group in `pyproject.toml`.
-
-## Publishing the package on PyPI
-
-Publishing the package on PyPI requires that you have API tokens for the test and production PyPI servers. You can find these tokens in your PyPI account settings. Create a `.env` file by coping `.env.copy` and add your tokens to this file.
-
-We use semantic versioning of the form `MAJOR.MINOR.PATCH`. See [semver.org](https://semver.org/) for more information. When you're ready to release a new version:
-
-1. Update the `version` field in `pyproject.toml` to the new version number
-2. Commit the change: `git commit -am "Bump version to X.Y.Z"`
-3. Create a git tag matching the version:
-
-```bash
-RELEASE_VERSION=0.1.0
-git tag -a v${RELEASE_VERSION} -m "Release version ${RELEASE_VERSION}"
-git push origin v${RELEASE_VERSION}
-```
-
-__Before creating the tag, make sure that your local git repository is on `main`, is up-to-date, and does not contain uncommitted changes!__
-
-If you need to delete a tag you've created:
-
-```bash
-git tag -d v${RELEASE_VERSION}
-```
-
-If you already pushed the deleted tag to GitHub, also delete it from the remote:
-
-```bash
-git push origin :refs/tags/v${RELEASE_VERSION}
-```
-
-Once you've created the correct new tag, build the package:
-```bash
-make build
-```
-
-You should see an output that looks like this:
-```
-Building glass-box-umap (0.1.0)
-  - Building sdist
-  - Built glass-box-umap-0.1.0.tar.gz
-  - Building wheel
-```
-
-The build artifacts are written to the `dist/` directory.
-
-__Make sure that the version number in the output from `make build` matches the one in `pyproject.toml` and the git tag!__
-
-If it does not, double-check that you updated the `version` field in `pyproject.toml` before creating the tag.
-
-Next, check that you can publish the package to the PyPI test server:
-
-```bash
-make build-and-test-publish
-```
-
-The `build-and-test-publish` command calls `uv build` to build the package and then `uv publish` to upload the build artifacts to the test server.
-
-Check that you can install the new version of the package from the test server:
-
-```bash
-pip install --index-url https://pypi.org/simple/ --extra-index-url https://test.pypi.org/simple/ glass-box-umap==${RELEASE_VERSION}
-```
-
-(For accurate installation testing: dependencies are installed from main PyPI (to avoid unreliable TestPyPI mirrors), while your package (not yet on main PyPI) is installed from TestPyPI.)
-
-If everything looks good, build and publish the package to the prod PyPI server:
-
-```bash
-make build-and-publish
-```
-
-Finally, check that you can install the new version of the package from the prod PyPI server:
-
-```bash
-pip install glass-box-umap==${RELEASE_VERSION}
-```
+Glass Box UMAP is part of [Arcadia Science's](https://www.arcadiascience.com/) commitment to open, reproducible research tools.

docs/_assets/rtd-badge.png

@@ -0,0 +1,15 @@
+.pub-card {
+    border: 2px solid #cfcfcf;
+    border-radius: 4px !important;
+    padding: 1rem;
+    margin-bottom: 1rem;
+    background: #eef3f9;
+}
+
+div.nbinput.container div.input_area div[class*=highlight] > pre {
+    padding: 15px !important;
+}
+
+div.nbinput.container {
+    margin-bottom: 1rem;
+}

docs/_static/css/cards.css

@@ -0,0 +1,4 @@
+h2, h3, h4, h5, h6 {
+    font-family: "Atkinson Hyperlegible Next", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    font-weight: 700;
+}

docs/_static/css/headings.css

@@ -0,0 +1,34 @@
+dl.py .base-classes {
+    font-family: var(--font-stack--monospace);
+    font-size: var(--api-font-size);
+    font-weight: 700;
+}
+
+dl.py .rubric {
+    text-transform: uppercase;
+    font-size: 0.75em;
+    font-weight: 700;
+    letter-spacing: 0.1em;
+    color: var(--color-foreground-secondary);
+    border-bottom: 1px solid var(--color-foreground-border);
+    padding-bottom: 0.3em;
+    margin-top: 1.5em;
+    margin-bottom: 0.75em;
+}
+
+p.param-sig {
+    font-family: var(--font-stack--monospace);
+    font-size: var(--api-font-size);
+    font-weight: 700;
+}
+
+p.param-desc {
+    margin-left: 1.5em;
+    margin-top: 0;
+}
+
+dd.return-type p {
+    font-family: var(--font-stack--monospace);
+    font-size: var(--api-font-size);
+    font-weight: 700;
+}

docs/_static/css/rubric.css

@@ -0,0 +1,7 @@
+.toggle-hidden dl.py.class,
+.toggle-hidden dl.py.function,
+.toggle-hidden dl.py.method,
+.toggle-hidden dl.py.attribute,
+.toggle-hidden dl.py.data {
+    display: none !important;
+}

docs/_static/css/sphinx-togglebutton.css

@@ -0,0 +1,12 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation.
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   {% for page in pages|selectattr("is_top_level_object") %}
+   {{ page.include_path }}
+   {% endfor %}

docs/_templates/autoapi/index.rst

@@ -0,0 +1,41 @@
+{% macro _render_item_name(obj, sig=False) -%}
+:py:obj:`{{ obj.name }} <{{ obj.id }}>`
+     {%- if sig -%}
+       \ (
+       {%- for arg in obj.obj.args -%}
+          {%- if arg[0] %}{{ arg[0]|replace('*', '\*') }}{% endif -%}{{  arg[1] -}}
+          {%- if not loop.last  %}, {% endif -%}
+       {%- endfor -%}
+       ){%- endif -%}
+{%- endmacro %}
+
+{% macro _item(obj, sig=False, label='') %}
+   * - {{ _render_item_name(obj, sig) }}
+     - {% if label %}:summarylabel:`{{ label }}` {% endif %}{% if obj.summary %}{{ obj.summary }}{% else %}\-{% endif +%}
+{% endmacro %}
+
+{% macro auto_summary(objs, title='') -%}
+.. list-table:: {{ title }}
+   :header-rows: 0
+   :widths: auto
+   :class: summarytable
+
+  {% for obj in objs -%}
+    {%- set sig = (obj.type in ['method', 'function'] and not 'property' in obj.properties) -%}
+
+    {%- if 'property' in obj.properties -%}
+      {%- set label = 'prop' -%}
+    {%- elif 'classmethod' in obj.properties -%}
+      {%- set label = 'class' -%}
+    {%- elif 'abstractmethod' in obj.properties -%}
+      {%- set label = 'abc' -%}
+    {%- elif 'staticmethod' in obj.properties -%}
+      {%- set label = 'static' -%}
+    {%- else -%}
+      {%- set label = '' -%}
+    {%- endif -%}
+
+    {{- _item(obj, sig=sig, label=label) -}}
+  {%- endfor -%}
+
+{% endmacro %}