docs: create (#68)

* docs: create
* docs: config
* build: jaxtyping
* docs: add jinja
* docs: add operators to API
* docs: logo
* docs: show source
* docs: allow_inspection
* fix: schur

Signed-off-by: nstarman <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.pre-commit-config.yaml

@@ -36,7 +36,6 @@ repos:
       - id: name-tests-test
         args: ["--pytest-test-first"]
         exclude: tests/myarray.py
-      - id: requirements-txt-fixer
       - id: trailing-whitespace
 
   - repo: https://github.com/pre-commit/pygrep-hooks

.readthedocs.yml

@@ -1,15 +1,19 @@
-# Read the Docs configuration file
+# Read the Docs configuration file for MkDocs projects
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
+# Required
 version: 2
 
+# Set the version of Python and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
-sphinx:
-  configuration: docs/conf.py
+    python: "3.12"
 
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
 python:
   install:
     - method: pip

docs/.htaccess

@@ -0,0 +1 @@
+ErrorDocument 404 /equinox/404.html

docs/_static/.README.md

@@ -0,0 +1,2 @@
+The favicon is `math-integral` from https://materialdesignicons.com, found by
+way of https://pictogrammers.com. (The logo is `math-integral-box`.)

docs/_static/custom_css.css

@@ -0,0 +1,168 @@
+/* Fix /page#foo going to the top of the viewport and being hidden by the navbar */
+html {
+  scroll-padding-top: 50px;
+}
+
+/* Fit the Twitter handle alongside the GitHub one in the top right. */
+
+div.md-header__source {
+  width: revert;
+  max-width: revert;
+}
+
+a.md-source {
+  display: inline-block;
+}
+
+.md-source__repository {
+  max-width: 100%;
+}
+
+/* Emphasise sections of nav on left hand side */
+
+nav.md-nav {
+  padding-left: 5px;
+}
+
+nav.md-nav--secondary {
+  border-left: revert !important;
+}
+
+.md-nav__title {
+  font-size: 0.9rem;
+}
+
+.md-nav__item--section > .md-nav__link {
+  font-size: 0.9rem;
+}
+
+/* Indent autogenerated documentation */
+
+div.doc-contents {
+  padding-left: 25px;
+  border-left: 4px solid rgba(230, 230, 230);
+}
+
+/* Increase visibility of splitters "---" */
+
+[data-md-color-scheme="default"] .md-typeset hr {
+  border-bottom-color: rgb(0, 0, 0);
+  border-bottom-width: 1pt;
+}
+
+[data-md-color-scheme="slate"] .md-typeset hr {
+  border-bottom-color: rgb(230, 230, 230);
+}
+
+/* More space at the bottom of the page */
+
+.md-main__inner {
+  margin-bottom: 1.5rem;
+}
+
+/* Remove prev/next footer buttons */
+
+.md-footer__inner {
+  display: none;
+}
+
+/* Change font sizes */
+
+html {
+  /* Decrease font size for overall webpage
+       Down from 137.5% which is the Material default */
+  font-size: 110%;
+}
+
+.md-typeset .admonition {
+  /* Increase font size in admonitions */
+  font-size: 100% !important;
+}
+
+.md-typeset details {
+  /* Increase font size in details */
+  font-size: 100% !important;
+}
+
+.md-typeset h1 {
+  font-size: 1.6rem;
+}
+
+.md-typeset h2 {
+  font-size: 1.5rem;
+}
+
+.md-typeset h3 {
+  font-size: 1.3rem;
+}
+
+.md-typeset h4 {
+  font-size: 1.1rem;
+}
+
+.md-typeset h5 {
+  font-size: 0.9rem;
+}
+
+.md-typeset h6 {
+  font-size: 0.8rem;
+}
+
+/* Bugfix: remove the superfluous parts generated when doing:
+
+??? Blah
+
+    ::: library.something
+*/
+
+.md-typeset details .mkdocstrings > h4 {
+  display: none;
+}
+
+.md-typeset details .mkdocstrings > h5 {
+  display: none;
+}
+
+/* Change default colours for <a> tags */
+
+[data-md-color-scheme="default"] {
+  --md-typeset-a-color: rgb(0, 189, 164) !important;
+}
+[data-md-color-scheme="slate"] {
+  --md-typeset-a-color: rgb(0, 189, 164) !important;
+}
+
+/* Highlight functions, classes etc. type signatures. Really helps to make clear where
+   one item ends and another begins. */
+
+[data-md-color-scheme="default"] {
+  --doc-heading-color: #ddd;
+  --doc-heading-border-color: #ccc;
+  --doc-heading-color-alt: #f0f0f0;
+}
+[data-md-color-scheme="slate"] {
+  --doc-heading-color: rgb(25, 25, 33);
+  --doc-heading-border-color: rgb(25, 25, 33);
+  --doc-heading-color-alt: rgb(33, 33, 44);
+  --md-code-bg-color: rgb(38, 38, 50);
+}
+
+h4.doc-heading {
+  /* NOT var(--md-code-bg-color) as that's not visually distinct from other code blocks.*/
+  background-color: var(--doc-heading-color);
+  border: solid var(--doc-heading-border-color);
+  border-width: 1.5pt;
+  border-radius: 2pt;
+  padding: 0pt 5pt 2pt 5pt;
+}
+h5.doc-heading,
+h6.heading {
+  background-color: var(--doc-heading-color-alt);
+  border-radius: 2pt;
+  padding: 0pt 5pt 2pt 5pt;
+}
+
+/* Make errors in notebooks have scrolling */
+.output_error > pre {
+  overflow: auto;
+}

docs/_static/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true,
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex",
+  },
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise();
+});

docs/api/array_api.md

@@ -0,0 +1,3 @@
+# quaxed.array_api
+
+::: quaxed.array_api

docs/api/lax.md

@@ -0,0 +1,3 @@
+# quaxed.lax
+
+::: quaxed.lax

docs/api/numpy.md

@@ -0,0 +1,3 @@
+# quaxed.numpy
+
+::: quaxed.numpy

docs/api/operator.md

@@ -0,0 +1,3 @@
+# quaxed.operator
+
+::: quaxed.operator

docs/api/quaxed.md

@@ -0,0 +1,3 @@
+# quaxed
+
+::: quaxed

docs/api/scipy.md

@@ -0,0 +1,3 @@
+# quaxed.scipy
+
+::: quaxed.scipy

docs/index.md

@@ -1,17 +1,56 @@
-# quaxed
+# Quaxed
 
-```{toctree}
-:maxdepth: 2
-:hidden:
+pre-`quaxified` JAX functions.
 
+`quax` enables JAX + multiple dispatch + custom array-ish objects. `quaxed`
+means you don't have to wrap every function in `quax.quaxify` wrappers every
+time.
+
+## Installation
+
+```bash
+pip install quaxed
+```
+
+## Getting started
+
+Import whatever library you need as a drop-in replacement for its JAX
+counterpart.
+
+To see the API check out the [`quaxed`](./api/quaxed.md) in the left bar.
+
+```python
+import quaxed.numpy as jnp
+
+x = jnp.linspace(0.0, 1.0, num=3)
+
+print(jnp.cos(x))
+# [1.         0.87758255 0.5403023 ]
 ```
 
-```{include} ../README.md
-:start-after: <!-- SPHINX-START -->
+The advantage of `quaxed` over plain `JAX` is that every function is `quaxify`'d
+and will work with properly formulated array-ish objects.
+
+For this example we use [unxt](https://github.com/GalacticDyanamics/quax)'s
+`Quantity` for unitful calculations.
+
+```python
+from unxt import Quantity
+
+x = Quantity(jnp.linspace(0.0, 1.0, num=3), "deg")
+
+print(jnp.cos(x))
+# Quantity['dimensionless'](Array([1.       , 0.9999619, 0.9998477], dtype=float32), unit='')
 ```
 
-## Indices and tables
+## See also: other libraries in the Quax ecosystem
+
+[Quax](https://github.com/patrick-kidger/quax): the base library.
+
+[unxt](https://github.com/GalacticDyanamics/quax): Units and Quantities in Jax.
+
+[coordinax](https://github.com/GalacticDyanamics/coordinax): Vector
+representations (built on `unxt`).
 
-- {ref}`genindex`
-- {ref}`modindex`
-- {ref}`search`
+[galax](https://github.com/GalacticDyanamics/galax): Galactic dynamics in Jax
+(built on `unxt` and `coordinax`).