docs: sort out cross-referencing

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/docs/bundles.rst b/docs/bundles.rst
index 40ccf9abddb92888938f56ad15d1fbea5eacaf62..1faf2d8d7939a5d10c7367d4825e1d20fad8ed93 100644 (file)
--- a/docs/bundles.rst
+++ b/docs/bundles.rst
@@ -35,7 +35,7 @@ Bundles are zipfiles.  They can contain:
    ``GAME`` is the game spec name (e.g., ``stoat-fest`` above.)
 
  * ``library/LIB.toml``: Description of a piece shape library,
-   for a library named ``LIB``.  See _`Shape libraries`.
+   for a library named ``LIB``.  See :doc:`shapelibs`.
 
 These files are all in TOML format.  TOML ia an INI-file-like format
 designed for human editing and flexibility.  See the `TOML

diff --git a/docs/conf.py b/docs/conf.py
index 2c65344cfc357ae6e470cd2f112b9282e961783e..7a58ede2bc91728336c5cffbf43195fb993202dc 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -40,7 +40,9 @@ release = ''
 # ones.
 extensions = [
     'recommonmark',
+    'sphinx.ext.autosectionlabel',
 ]
+autosectionlabel_prefix_document = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

diff --git a/docs/gamespec.rst b/docs/gamespec.rst
index 30d69ee8771d8dda45771a839fe1c7ead4029f75..db657cbd2767be87cebfbebdacde7ea73922b5b4 100644 (file)
--- a/docs/gamespec.rst
+++ b/docs/gamespec.rst
@@ -28,3 +28,8 @@ level:
 
  * ``pieces``: Array of _`Piece spec`.  Defines the initial pieces
    and their layout.  Each entry is a piece spec sub-table.
+
+Piece Specs
+-----------
+
+XXX todo

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index c2aaf6dbab391c5256d364a16af574984e4af07f..870ae6eeaa132881aa4b2aa1f34e69e8b49a4cac 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -36,7 +36,7 @@ piece (for example, with ``otter library-add``).
 Pieces in shape libraries cannot have "behaviours": they can't do
 anything "special" like react to being moved or clicked on.  Pieces
 with special functionality do exist, but they are built into Otter.
-(See _`Piece specs` for all the kinds of piece.)
+(See :ref:`gamespec:Piece specs` for all the kinds of piece.)
 
 A library consists of a **catalogue**, and a set of **image files**
 which contain the actual appearances.  When a library is in a bundle
@@ -190,7 +190,7 @@ Mandatory parameters
    supported.
 
  * ``files``: [multi-line string].  The list of pieces to define,
-   one per line.  See _`Files entry`.
+   one per line.  See `Files entry`_.
 
 Important parameters
 ````````````````````
@@ -237,12 +237,13 @@ Parameters for defining faces
    appearance.  (It is a bad idea to have the game contain state which
    is not visible to the players.)  Not compatible with ``back``.
 
- * ``back``: [_`Piece spec`].  The back of this piece looks like some
-   other piece (typically, another library item such as a card back).
-   If specified, the piece will have two faces: the one implied by its
-   ``files`` entry, and a 2nd face looking like ``back``.  If you want
-   to make the piece be occultable, you must also specify
-   ``occulted``.  ``back`` is not compatible with ``flip``.
+ * ``back``: [:ref:`Piece spec <gamespec:Piece Specs>`].  The back of
+   this piece looks like some other piece (typically, another library
+   item such as a card back).  If specified, the piece will have two
+   faces: the one implied by its ``files`` entry, and a 2nd face
+   looking like ``back``.  If you want to make the piece be
+   occultable, you must also specify ``occulted``.  ``back`` is not
+   compatible with ``flip``.
 
 Other group parameters
 ```````````````````````