Initial docs

.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
 
       - name: Run the example notebooks
         run: |
-          cd examples
+          cd docs/examples
           for f in *.ipynb; do
             jupyter nbconvert --to notebook --execute $f || exit 1
           done

.gitignore

@@ -3,6 +3,7 @@ pyabc2/sources/_*
 !pyabc2/sources/__init__.py
 poetry.lock
 venv*/
+docs/api/
 
 
 # Byte-compiled / optimized / DLL files

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
+
+sphinx:
+  configuration: docs/conf.py

docs/api.rst

@@ -0,0 +1,58 @@
+===
+API
+===
+
+.. currentmodule:: pyabc2
+
+Note types
+==========
+
+.. autosummary::
+   :toctree: api/
+
+   PitchClass
+   Pitch
+   Note
+
+Alternative initializers:
+
+.. autosummary::
+   :toctree: api/
+
+   PitchClass.from_name
+   PitchClass.from_pitch
+
+   Pitch.from_name
+   Pitch.from_class_name
+   Pitch.from_class_value
+   Pitch.from_etf
+   Pitch.from_helmholtz
+   Pitch.from_pitch_class
+
+   Note.from_abc
+   Note.from_pitch
+
+Key type
+========
+
+.. autosummary::
+   :toctree: api/
+
+   Key
+   Key.parse_key
+
+Tune type
+=========
+
+.. autosummary::
+   :toctree: api/
+
+   Tune
+
+   Tune.abc
+   Tune.header
+   Tune.title
+   Tune.type
+   Tune.key
+   Tune.url
+   Tune.measures

docs/conf.py

@@ -0,0 +1,37 @@
+import pyabc2
+
+project = "PyABC2"
+copyright = "2021\u20132025 zmoon"
+author = "zmoon"
+
+version = pyabc2.__version__.split("+")[0]
+release = pyabc2.__version__
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "myst_nb",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+}
+
+exclude_patterns = ["_build"]
+
+html_theme = "furo"
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_preprocess_types = True
+napoleon_use_param = True
+napoleon_use_rtype = False
+
+autodoc_typehints = "description"
+autosummary_generate = True
+
+nb_execution_raise_on_error = True

examples/modes.ipynb → docs/examples/modes.ipynb

@@ -5,6 +5,8 @@
    "id": "0",
    "metadata": {},
    "source": [
+    "# Modes\n",
+    "\n",
     "Check the modes."
    ]
   },

examples/sources.ipynb → docs/examples/sources.ipynb

@@ -1,9 +1,17 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Tune sources"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "0",
+   "id": "1",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -12,7 +20,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "1",
+   "id": "2",
    "metadata": {},
    "source": [
     "## Norbeck"
@@ -21,7 +29,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "2",
+   "id": "3",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -31,7 +39,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "3",
+   "id": "4",
    "metadata": {},
    "source": [
     "## The Session"
@@ -40,7 +48,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "4",
+   "id": "5",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -51,7 +59,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "5",
+   "id": "6",
    "metadata": {},
    "outputs": [],
    "source": [

examples/types.ipynb → docs/examples/types.ipynb

@@ -5,6 +5,8 @@
    "id": "0",
    "metadata": {},
    "source": [
+    "# Types and reprs\n",
+    "\n",
     "Checking the Jupyter reprs."
    ]
   },
@@ -19,10 +21,18 @@
     "from pyabc2.sources import load_example_abc"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
+   "source": [
+    "## Pitch class"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "2",
+   "id": "3",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -32,7 +42,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "3",
+   "id": "4",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -43,17 +53,25 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "4",
+   "id": "5",
    "metadata": {},
    "outputs": [],
    "source": [
     "Fb.equivalent_sharp"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "## Pitch"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "5",
+   "id": "7",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -63,17 +81,25 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "6",
+   "id": "8",
    "metadata": {},
    "outputs": [],
    "source": [
     "pyabc2.Pitch.from_name(\"Fb4\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "9",
+   "metadata": {},
+   "source": [
+    "## Note"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "7",
+   "id": "10",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -83,7 +109,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "8",
+   "id": "11",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -93,17 +119,48 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "9",
+   "id": "12",
    "metadata": {},
    "outputs": [],
    "source": [
     "pyabc2.Note.from_abc(\"D,,3/\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "13",
+   "metadata": {},
+   "source": [
+    "## Interval"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "10",
+   "id": "14",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = pyabc2.Pitch.from_name(\"D3\")\n",
+    "\n",
+    "for dv in range(-14, 32):\n",
+    "    p_ = pyabc2.Pitch(p.value + dv)\n",
+    "    i = p_ - p\n",
+    "    print(p.unicode(), \"→\", p_.unicode(), \"\\t\", i)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "15",
+   "metadata": {},
+   "source": [
+    "## Tune"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "16",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -115,7 +172,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "11",
+   "id": "17",
    "metadata": {},
    "outputs": [],
    "source": [