From 03eb61cd5da9e6867ebe57fe997e4b44cbd48559 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz <me@kennethreitz.org>
Date: Sun, 22 Mar 2026 21:07:12 -0400
Subject: [PATCH] Rewrite docs landing page with richer examples

Show Key class, chord progressions, chord identification, interval
naming, and labeled fingerings in the hero code block. Add pip install
line, CLI examples, and a Highlights section summarizing all features.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/index.rst | 60 +++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 47 insertions(+), 13 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index abf56a5..48859df 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,26 +1,60 @@
 PyTheory: Music Theory for Humans
 =================================
 
-**PyTheory** is a Python library that makes exploring music theory approachable.
-Work with tones, scales, chords, and fretboards using a clean, Pythonic API.
+**PyTheory** is a Python library that makes exploring music theory
+approachable and fun. Work with tones, scales, chords, keys, and
+instruments using a clean, Pythonic API.
+
+::
+
+   $ pip install pytheory
 
 .. code-block:: python
 
-   from pytheory import TonedScale, Fretboard, CHARTS
+   from pytheory import Key, Chord, Tone, Fretboard
 
-   # Build a C major scale
-   c_major = TonedScale(tonic="C4")["major"]
-   print(c_major.note_names)
-   # ['C', 'D', 'E', 'F', 'G', 'A', 'B', 'C']
+   # Explore a key
+   key = Key("C", "major")
+   key.chords
+   # ['C major', 'D minor', 'E minor', 'F major',
+   #  'G major', 'A minor', 'B diminished']
 
-   # Build a triad from the scale
-   chord = c_major.triad(0)  # C major triad
-   for tone in chord:
-       print(f"{tone}: {tone.frequency:.1f} Hz")
+   # Build a chord progression
+   [c.identify() for c in key.progression("I", "V", "vi", "IV")]
+   # ['C major', 'G major', 'A minor', 'F major']
 
-   # Get guitar fingerings
+   # Identify any chord
+   Chord.from_tones("Bb", "D", "F").identify()   # 'Bb major'
+
+   # Name the interval
+   c4 = Tone.from_string("C4", system="western")
+   c4.interval_to(c4 + 7)   # 'perfect 5th'
+
+   # Guitar fingerings with labeled strings
    fb = Fretboard.guitar()
-   print(CHARTS["western"]["C"].fingering(fretboard=fb))
+   fb.fingering(0, 1, 0, 2, 3, 0)
+   # Fingering(e=0, B=1, G=0, D=2, A=3, E=0)  →  C major
+
+It also works from the command line::
+
+   $ pytheory key G major
+   $ pytheory chord C E G
+   $ pytheory play Am7 --synth triangle
+
+Highlights
+----------
+
+- **Tones**: frequencies, MIDI, intervals, transposition, circle of fifths,
+  overtone series, 3 temperaments (equal, Pythagorean, meantone)
+- **Scales**: 40+ scales across 6 musical systems — Western, Indian,
+  Arabic, Japanese, Blues, Javanese Gamelan
+- **Chords**: 17 chord types identified automatically, Roman numeral
+  analysis, tension scoring, voice leading, consonance/dissonance
+- **Keys**: key detection, signatures, progressions (Roman numerals and
+  Nashville numbers), borrowed chords, secondary dominants
+- **Instruments**: 25 presets (guitar, bass, ukulele, mandolin, violin,
+  banjo, oud, sitar, erhu, and more) with fingering generation
+- **Audio**: sine, sawtooth, and triangle wave playback + WAV export
 
 .. toctree::
    :maxdepth: 2