Reorganize PGN docs

niklasf · niklasf · commit db03057a5e60 · 2017-10-14T02:37:12.000+02:00
diff --git a/chess/pgn.py b/chess/pgn.py
@@ -751,18 +751,29 @@ def read_game(handle, Visitor=GameModelCreator):
     """
     Reads a game from a file opened in text mode.
 
+    >>> import chess.pgn
+    >>>
     >>> pgn = open("data/pgn/kasparov-deep-blue-1997.pgn")
+    >>>
     >>> first_game = chess.pgn.read_game(pgn)
     >>> second_game = chess.pgn.read_game(pgn)
     >>>
     >>> first_game.headers["Event"]
     'IBM Man-Machine, New York USA'
+    >>>
+    >>> board = first_game.board()
+    >>> for move in first_game.main_line():
+    ...     board.push(move)
+    ...
+    >>> board
+    Board('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1')
 
     By using text mode the parser does not need to handle encodings. It is the
     callers responsibility to open the file with the correct encoding.
     PGN files are ASCII or UTF-8 most of the time. So the following should
     cover most relevant cases (ASCII, UTF-8, UTF-8 with BOM).
 
+    >>> # Python 3
     >>> pgn = open("data/pgn/kasparov-deep-blue-1997.pgn", encoding="utf-8-sig")
 
     Use :class:`~io.StringIO` to parse games from a string.
diff --git a/docs/pgn.rst b/docs/pgn.rst
@@ -1,6 +1,44 @@
 PGN parsing and writing
 =======================
 
+Parsing
+-------
+
+.. autofunction:: chess.pgn.read_game
+
+Writing
+-------
+
+If you want to export your game game with all headers, comments and variations
+you can use:
+
+>>> import chess
+>>> import chess.pgn
+>>>
+>>> game = chess.pgn.Game()
+>>> game.headers["Event"] = "Example"
+>>> node = game.add_variation(chess.Move.from_uci("e2e4"))
+>>> node = node.add_variation(chess.Move.from_uci("e7e5"))
+>>> node.comment = "Comment"
+>>>
+>>> print(game)
+[Event "Example"]
+[Site "?"]
+[Date "????.??.??"]
+[Round "?"]
+[White "?"]
+[Black "?"]
+[Result "*"]
+<BLANKLINE>
+1. e4 e5 { Comment } *
+
+Remember that games in files should be separated with extra blank lines.
+
+>>> print(game, file=open("/dev/null", "w"), end="\n\n")
+
+Use the :class:`~chess.pgn.StringExporter()` or
+:class:`~chess.pgn.FileExporter()` visitors if you need more control.
+
 Game model
 ----------
 
@@ -75,39 +113,6 @@ headers.
 
         A list of child nodes.
 
-Parsing
--------
-
-.. autofunction:: chess.pgn.read_game
-
-.. autofunction:: chess.pgn.scan_headers
-
-.. autofunction:: chess.pgn.scan_offsets
-
-Writing
--------
-
-If you want to export your game game with all headers, comments and variations
-you can use:
-
->>> print(game)
-[Event "?"]
-[Site "?"]
-[Date "????.??.??"]
-[Round "?"]
-[White "?"]
-[Black "?"]
-[Result "*"]
-<BLANKLINE>
-1. e4 e5 { Comment } *
-
-Remember that games in files should be separated with extra blank lines.
-
->>> print(game, file=handle, end="\n\n")
-
-Use the :class:`~chess.pgn.StringExporter()` or
-:class:`~chess.pgn.FileExporter()` visitors if you need more control.
-
 Visitors
 --------
 
@@ -140,3 +145,12 @@ like ``!``, ``?``, ``!!``, etc. are also converted to NAGs.
 .. autodata:: chess.pgn.NAG_BLUNDER
 .. autodata:: chess.pgn.NAG_SPECULATIVE_MOVE
 .. autodata:: chess.pgn.NAG_DUBIOUS_MOVE
+
+Skimming
+--------
+
+These functions allow quickly skimming games without fully parsing them.
+
+.. autofunction:: chess.pgn.scan_headers
+
+.. autofunction:: chess.pgn.scan_offsets
