feat: Revamp README and documentation for clarity and performance insights

- Updated README to reflect a more concise description of the library, emphasizing speed and efficiency.
- Enhanced installation instructions and added quick start examples for better user onboarding.
- Improved documentation structure, including detailed sections for core API, engine usage, and performance metrics.
- Removed outdated hub documentation and streamlined content for clarity.
- Bumped version to 1.6.1 in `uv.lock` to reflect recent changes.
- Added type aliases for Sphinx autodoc to improve documentation generation.

Author: miskibin

docs/source/conf.py

@@ -5,14 +5,14 @@
 sys.path.insert(0, os.path.abspath("../.."))
 import draughts
 
-# Do not resolve these.
-# autodoc_type_aliases = {
-#     "Square": "chess.Square",
-#     "Color": "chess.Color",
-#     "PieceType": "chess.PieceType",
-#     "Bitboard": "chess.Bitboard",
-#     "IntoSquareSet": "chess.IntoSquareSet",
-# }
+# Type aliases for Sphinx autodoc - show public names, not internal module paths
+autodoc_type_aliases = {
+    "StandardBoard": "draughts.StandardBoard",
+    "AmericanBoard": "draughts.AmericanBoard",
+    "FrisianBoard": "draughts.FrisianBoard",
+    "RussianBoard": "draughts.RussianBoard",
+    "Board": "draughts.Board",
+}
 
 # Autodoc.
 extensions = [

docs/source/core.rst

@@ -1,80 +1,62 @@
-Core
-====
+Core API
+========
 
-Colors
+Boards
 ------
 
-Constants for the side to move or the color of a piece.
-
-.. py:data:: draughts.Color.WHITE
-    :type: draughts.Color
-    :value: -1
-
-    Constant representing the white side.
-
-.. py:data:: draughts.Color.BLACK
-    :type: draughts.Color
-    :value: 1
-
-    Constant representing the black side.
-
-Example usage::
+All board classes inherit from :class:`~draughts.BaseBoard`.
+Use ``Board`` (alias for ``StandardBoard``) for the most common variant.
 
-    from draughts import StandardBoard, Color
-    
-    board = StandardBoard()
-    print(board.turn)  # Color.WHITE
-    
-    # Toggle turn
-    if board.turn == Color.WHITE:
-        print("White to move")
-
-Figures (Piece Types)
----------------------
-
-Constants representing piece types in draughts.
-
-.. py:data:: draughts.Figure.BLACK_KING
-    :type: draughts.Figure
-    :value: 2
+.. autoclass:: draughts.StandardBoard
+    :members:
+    :inherited-members:
+    :show-inheritance:
 
-    A black king piece.
+.. autoclass:: draughts.AmericanBoard
+    :members:
+    :show-inheritance:
+    :noindex:
 
-.. py:data:: draughts.Figure.BLACK_MAN
-    :type: draughts.Figure
-    :value: 1
+.. autoclass:: draughts.FrisianBoard
+    :members:
+    :show-inheritance:
+    :noindex:
 
-    A black man (regular piece).
+.. autoclass:: draughts.RussianBoard
+    :members:
+    :show-inheritance:
+    :noindex:
 
-.. py:data:: draughts.Figure.WHITE_KING
-    :type: draughts.Figure
-    :value: -2
+BaseBoard
+~~~~~~~~~
 
-    A white king piece.
+.. autoclass:: draughts.BaseBoard
+    :members:
+    :noindex:
 
-.. py:data:: draughts.Figure.WHITE_MAN
-    :type: draughts.Figure
-    :value: -1
+Moves
+-----
 
-    A white man (regular piece).
+.. autoclass:: draughts.Move
+    :members:
 
-.. py:data:: draughts.Figure.EMPTY
-    :type: draughts.Figure
-    :value: 0
+Types
+-----
 
-    An empty square.
+.. autoclass:: draughts.Color
+    :members:
+    :undoc-members:
 
-Squares
--------
+.. autoclass:: draughts.Figure
+    :members:
+    :undoc-members:
 
-In py-draughts, squares are numbered from 1 to 50 for standard (10×10) boards 
-and 1 to 32 for American (8×8) boards. Only dark squares are numbered and used 
-in the game.
+Square Numbering
+----------------
 
-Standard Board (10×10)
-~~~~~~~~~~~~~~~~~~~~~~
+Only dark squares are playable and numbered.
 
-Squares are numbered 1-50:
+**Standard Board (10×10)** - Squares 1-50:
 
 .. code-block:: text
 
@@ -89,10 +71,7 @@ Squares are numbered 1-50:
     41 42 43 44 45
   46 47 48 49 50
 
-American/Russian Board (8×8)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Both American and Russian draughts use an 8×8 board with squares numbered 1-32:
+**American/Russian Board (8×8)** - Squares 1-32:
 
 .. code-block:: text
 
@@ -105,155 +84,32 @@ Both American and Russian draughts use an 8×8 board with squares numbered 1-32:
     25 26 27 28
   29 30 31 32
 
-Board Factory
--------------
-
-.. autofunction:: draughts.get_board
-
-Example::
-
-    from draughts import get_board
-    
-    # Create a standard board
-    board = get_board('standard')
-    
-    # Create an American board
-    board = get_board('american')
-    
-    # Create a Frisian board (with orthogonal captures)
-    board = get_board('frisian')
-    
-    # Create a Russian board (flying kings, free capture choice)
-    board = get_board('russian')
-    
-    # Create a board from FEN
-    board = get_board('standard', fen='W:W31,32,33:B18,19,20')
-
-Boards
-------
-
-All board classes inherit from the base :class:`draughts.boards.base.BaseBoard` class.
-
-StandardBoard
-~~~~~~~~~~~~~
-
-.. autoclass:: draughts.boards.standard.Board
-    :members:
-    :inherited-members:
-    :show-inheritance:
+Notation
+--------
 
-AmericanBoard
-~~~~~~~~~~~~~
+**FEN** (Forsyth-Edwards Notation) represents board positions::
 
-.. autoclass:: draughts.boards.american.Board
-    :members:
-    :inherited-members:
-    :show-inheritance:
+    W:W31,32,33:B18,19,20     # W = White to move, pieces listed
+    W:WK10,K20:BK35,K45       # K prefix = King
 
-FrisianBoard
-~~~~~~~~~~~~
+**PDN** (Portable Draughts Notation) records games::
 
-.. autoclass:: draughts.boards.frisian.Board
-    :members:
-    :inherited-members:
-    :show-inheritance:
-
-RussianBoard
-~~~~~~~~~~~~
-
-Russian draughts uses an 8×8 board like American checkers, but with key differences:
-
-- **Flying kings** that move any distance diagonally (like International)
-- **Men capture backward** (unlike American where men only capture forward)
-- **Free capture choice** - not required to take maximum captures (unlike International)
-- **Mid-capture promotion** - if a man reaches the promotion rank during a capture, it becomes a king and continues capturing as a king
-
-.. autoclass:: draughts.boards.russian.Board
-    :members:
-    :inherited-members:
-    :show-inheritance:
-
-BaseBoard
-~~~~~~~~~
-
-.. autoclass:: draughts.boards.base.BaseBoard
-    :members:
-
-Moves
------
-
-.. autoclass:: draughts.move.Move
-    :members:
-
-Example::
-
-    from draughts import StandardBoard
-    
-    board = StandardBoard()
-    
-    # Make a move using UCI notation
-    move = board.push_uci("31-27")
-    print(move)  # Move: 31->27
-    
-    # Iterate through legal moves
-    for move in board.legal_moves:
-        print(move)
-    
-    # Undo the last move
-    board.pop()
-
-FEN Notation
-------------
-
-py-draughts uses FEN (Forsyth-Edwards Notation) adapted for draughts to represent board positions.
-
-Format::
-
-    [Side to move]:[White pieces]:[Black pieces]
-
-Example::
-
-    W:W31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
-
-Kings are prefixed with 'K'::
-
-    W:WK10,K20:BK35,K45
+    [GameType "20"]
+    [Variant "Standard"]
+    1. 31-27 18-22 2. 27x18 12x23
 
 Usage::
 
-    from draughts import StandardBoard
-    
-    # From FEN
-    fen = "W:WK10,K20:BK35,K45"
-    board = StandardBoard.from_fen(fen)
-    
-    # To FEN
-    fen_string = board.to_fen()
-
-PDN Notation
-------------
-
-PDN (Portable Draughts Notation) is used for recording games, similar to PGN in chess.
-
-Format::
+    from draughts import Board
 
-    [GameType "20"]
-    [Variant "Standard (international) checkers"]
-    [Result "-"]
-    1. 31-27 32-28 2. 27-23 28-24
+    # From FEN
+    board = Board.from_fen("W:WK10,K20:BK35,K45")
 
-Usage::
+    # To FEN
+    print(board.fen)
 
-    from draughts import StandardBoard
-    
-    # Generate PDN
-    board = StandardBoard()
-    board.push_uci("31-27")
-    board.push_uci("19-23")
-    pdn = board.pdn
-    print(pdn)
-    
     # From PDN
-    pdn_string = '''[GameType "20"]
-    1. 32-28 19-23 2. 28x19 14x23'''
-    board = StandardBoard.from_pdn(pdn_string)
+    board = Board.from_pdn('[GameType "20"]\n1. 32-28 19-23')
+
+    # To PDN
+    print(board.pdn)