Merge pull request #43 from nsmith-/document

Documentation bonanza

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install nox
+        run: |
+          pip install nox
+
+      - name: Build documentation
+        run: |
+          nox -s build_api_docs
+          nox -s docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build/html

.gitignore

@@ -7,3 +7,6 @@ build
 dist
 .vscode
 src/rhalphalib/version.py
+docs/api
+docs/_build
+.nox

README.md

@@ -61,3 +61,15 @@ An example output of the final line is:
 Best fit r: 0.999999  -0.208174/+0.212715  (68% CL)
 Done in 0.59 min (cpu), 0.59 min (real)
 ```
+
+## Development
+
+Clone this repo, and edit! To run tests, we use
+[nox](https://nox.thea.codes/en/stable/index.html) to simplify the
+configuration. If `nox` is installed systemwide, then simply running `nox` in
+this directory will automatically create linting and testing virtual
+environments and run the tests.
+
+For vscode, you can set the python interpreter to `.nox/tests/bin/python`.
+
+To build docs, run `nox -s build_api_docs docs`.

docs/conf.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import importlib.metadata
+from typing import Any
+
+project = "rhalphalib"
+copyright = "2025, rhalphalib developers"
+author = "Nick Smith"
+version = release = importlib.metadata.version("rhalphalib")
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
+    "nbsphinx",
+]
+
+source_suffix = [".rst", ".md"]
+exclude_patterns = [
+    "_build",
+    "**.ipynb_checkpoints",
+    "Thumbs.db",
+    ".DS_Store",
+    ".env",
+    ".venv",
+]
+
+html_theme = "furo"
+
+html_theme_options: dict[str, Any] = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/nsmith-/rhalphalib",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+    "source_repository": "https://github.com/nsmith-/rhalphalib",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
+
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "hist": ("https://hist.readthedocs.io/en/latest/", None),
+}
+
+nitpick_ignore = [
+    ("py:class", "_io.StringIO"),
+    ("py:class", "_io.BytesIO"),
+]
+
+always_document_param_types = True

docs/index.md

@@ -0,0 +1,20 @@
+# rhalphalib
+
+```{include} ../README.md
+
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents:
+:hidden:
+Home <self>
+introduction.ipynb
+api/rhalphalib
+```
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`