docs: create (#149)

* docs: start
* build: add docs requirements

Signed-off-by: nstarman <[email protected]>

.pre-commit-config.yaml

@@ -73,6 +73,7 @@ repos:
       - id: prettier
         types_or: [yaml, markdown, html, css, scss, javascript, json]
         args: [--prose-wrap=always]
+        exclude: docs/api/quantities.md
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: "v1.11.1"

.readthedocs.yaml

@@ -1,15 +1,18 @@
-# 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
 
 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

README.md

@@ -1,10 +1,8 @@
 <h1 align='center'> unxt </h1>
 <h2 align="center">Unitful Quantities in JAX</h2>
 
-Unxt is unitful quantities and calculations in
-[JAX](https://jax.readthedocs.io/en/latest/), built on
-[Equinox](https://docs.kidger.site/equinox/) and
-[Quax](https://github.com/patrick-kidger/quax).
+Unxt is unitful quantities and calculations in [JAX][jax], built on
+[Equinox][equinox] and [Quax][quax].
 
 Yes, it supports auto-differentiation (`grad`, `jacobian`, `hessian`) and
 vectorization (`vmap`, etc).
@@ -63,8 +61,8 @@ except Exception as e:
 
 `unxt` is built on [`quax`](https://github.com/patrick-kidger/quax), which
 enables custom array-ish objects in JAX. For convenience we use the
-[`quaxed`](https://pypi.org/project/quaxed/) library, which is just a `quax`
-wrapper around `jax` to avoid boilerplate wrappers.
+[`quaxed`](https://pypi.org/project/quaxed/) library, which is just a
+`quax.quaxify` wrapper around `jax` to avoid boilerplate code.
 
 ```python
 from quaxed import grad, vmap
@@ -98,23 +96,25 @@ except ValueError as e:
 
 [![DOI][zenodo-badge]][zenodo-link]
 
-If you found this library to be useful in academic work, then please cite.
+If you found this library to be useful and want to support the development and
+maintenance of lower-level code libraries for the scientific community, please
+consider citing this work.
 
 ## Development
 
 [![Actions Status][actions-badge]][actions-link]
 
 We welcome contributions!
 
-<!-- SPHINX-START -->
-
 <!-- prettier-ignore-start -->
+[equinox]: https://docs.kidger.site/equinox/
+[jax]: https://jax.readthedocs.io/en/latest/
+[quax]: https://github.com/patrick-kidger/quax
+
 [actions-badge]:            https://github.com/GalacticDynamics/unxt/workflows/CI/badge.svg
 [actions-link]:             https://github.com/GalacticDynamics/unxt/actions
 [conda-badge]:              https://img.shields.io/conda/vn/conda-forge/unxt
 [conda-link]:               https://github.com/conda-forge/unxt-feedstock
-<!-- [github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
-[github-discussions-link]:  https://github.com/GalacticDynamics/unxt/discussions -->
 [pypi-link]:                https://pypi.org/project/unxt/
 [pypi-platforms]:           https://img.shields.io/pypi/pyversions/unxt
 [pypi-version]:             https://img.shields.io/pypi/v/unxt

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/experimental.md

@@ -0,0 +1,3 @@
+# unxt.experimental
+
+::: unxt.experimental

docs/api/quantities.md

@@ -0,0 +1,3 @@
+# unxt Quantity
+
+::: unxt._quantity

docs/api/unitsystems.md

@@ -0,0 +1,3 @@
+# unxt.unitsystems
+
+::: unxt.unitsystems