From 313578b0561fbfbcfa386442c6678fa3b54bda72 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 23 May 2021 12:59:23 +0100 Subject: [PATCH] docs: sort out cross-referencing Signed-off-by: Ian Jackson --- docs/bundles.rst | 2 +- docs/conf.py | 2 ++ docs/gamespec.rst | 5 +++++ docs/shapelibs.rst | 17 +++++++++-------- 4 files changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/bundles.rst b/docs/bundles.rst index 40ccf9ab..1faf2d8d 100644 --- 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 2c65344c..7a58ede2 100644 --- 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 30d69ee8..db657cbd 100644 --- 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 c2aaf6db..870ae6ee 100644 --- 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 `]. 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 ``````````````````````` -- 2.30.2