Update doc roles, add inline code highlighting.

Author: HexDecimal

docs/conf.py

@@ -378,7 +378,8 @@
 napoleon_use_param = True
 napoleon_use_rtype = True
 
-rst_epilog = ".. include:: /epilog.rst"
+rst_prolog = ".. include:: /prolog.rst"  # Added to the beginning of every source file.
+rst_epilog = ".. include:: /epilog.rst"  # Added to the end of every source file.
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {

docs/prolog.rst

@@ -0,0 +1,6 @@
+.. Add inline code roles to all sources
+.. role:: python(code)
+   :language: python
+
+.. role:: shell(code)
+   :language: shell

docs/tutorial/part-00.rst

@@ -1,3 +1,5 @@
+.. _part-0:
+
 Part 0 - Setting up a project
 ##############################################################################
 
@@ -18,7 +20,7 @@ First script
 ==============================================================================
 
 First start with a modern top-level script.
-Create a script in the project root folder called ``main.py`` which checks ``if __name__ == "__main__":`` and calls a ``main`` function.
+Create a script in the project root folder called ``main.py`` which checks :python:`if __name__ == "__main__":` and calls a ``main`` function.
 
 .. code-block:: python
 
@@ -33,6 +35,6 @@ In VSCode on the left sidebar is a **Run and Debug** tab.
 On this tab select **create a launch.json** file.
 This will prompt about what kind of program to launch.
 Pick ``Python``, then ``Module``, then when asked for the module name type ``main``.
-From now on the ``F5`` key will launch ``main.py`` in debug mode.
+From now on the :kbd:`F5` key will launch ``main.py`` in debug mode.
 
-Run the script now and ``"Hello World!"`` should be visible in the terminal output.
+Run the script now and ``Hello World!`` should be visible in the terminal output.

docs/tutorial/part-01.rst

@@ -1,3 +1,5 @@
+.. _part-1:
+
 Part 1 - Moving a player around the screen
 ##############################################################################
 
@@ -23,7 +25,7 @@ Loading a tileset and opening a window
 From here it is time to setup a ``tcod`` program.
 Download `Alloy_curses_12x12.png <https://raw.githubusercontent.com/HexDecimal/python-tcod-tutorial-2023/6b69bf9b5531963a0e5f09f9d8fe72a4001d4881/data/Alloy_curses_12x12.png>`_ and place this file in your projects ``data/`` directory.
 This tileset is from the `Dwarf Fortress tileset repository <https://dwarffortresswiki.org/index.php/DF2014:Tileset_repository>`_.
-These kinds of tilesets are always loaded with ``columns=16, rows=16, charmap=tcod.tileset.CHARMAP_CP437``.
+These kinds of tilesets are always loaded with :python:`columns=16, rows=16, charmap=tcod.tileset.CHARMAP_CP437`.
 
 Load the tileset with :any:`tcod.tileset.load_tilesheet` and then pass it to :any:`tcod.context.new`.
 These functions are part of modules which have not been imported yet, so new imports need to be added.
@@ -47,7 +49,7 @@ These functions are part of modules which have not been imported yet, so new imp
     ...
 
 If an import fails that means you do not have ``tcod`` installed on the Python environment you just used to run the script.
-If you use an IDE then make sure the Python environment it is using is correct and then run ``pip install tcod`` from the shell terminal within that IDE.
+If you use an IDE then make sure the Python environment it is using is correct and then run :shell:`pip install tcod` from the shell terminal within that IDE.
 
 If you run this script now then a window will open and then immediately close.
 If that happens without seeing a traceback in your terminal then the script is correct.
@@ -57,18 +59,18 @@ Configuring an event loop
 
 The next step is to keep the window open until the user closes it.
 
-Since nothing is displayed yet a :any:`Console` should be created with ``"Hello World"`` printed to it.
+Since nothing is displayed yet a :any:`Console` should be created with :python:`"Hello World"` printed to it.
 The size of the console can be used as a reference to create the context by adding the console to :any:`tcod.context.new`.
 
-Begin the main game loop with a ``while True:`` statement.
+Begin the main game loop with a :python:`while True:` statement.
 
 To actually display the console to the window the :any:`Context.present` method must be called with the console as a parameter.
 Do this first in the game loop before handing events.
 
 Events are checked by iterating over all pending events with :any:`tcod.event.wait`.
-Use the code ``for event in tcod.event.wait():`` to begin handing events.
-Test if an event is for closing the window with ``if isinstance(event, tcod.event.Quit):``.
-If this is True then you should exit the function with ``raise SystemExit``.
+Use the code :python:`for event in tcod.event.wait():` to begin handing events.
+Test if an event is for closing the window with :python:`if isinstance(event, tcod.event.Quit):`.
+If this is True then you should exit the function with :python:`raise SystemExit`.
 
 .. code-block:: python
     :emphasize-lines: 2,3,11-18
@@ -93,7 +95,7 @@ If this is True then you should exit the function with ``raise SystemExit``.
                         raise SystemExit()
     ...
 
-If you run this then you get a window saying ``"Hello World"``.
+If you run this then you get a window saying :python:`"Hello World"`.
 The window can be resized and the console will be stretched to fit the new resolution.
 
 An example game state
@@ -102,18 +104,18 @@ An example game state
 What exists now is not very interactive.
 The next step is to change state based on user input.
 
-Like ``tcod`` you'll need to install ``attrs`` with Pip, such as with ``pip install attrs``.
+Like ``tcod`` you'll need to install ``attrs`` with Pip, such as with :shell:`pip install attrs`.
 
 Start by adding an ``attrs`` class called ``ExampleState``.
-This a normal class with the ``@attrs.define(eq=False)`` decorator added.
+This a normal class with the :python:`@attrs.define(eq=False)` decorator added.
 
 This class should hold coordinates for the player.
 It should also have a ``on_draw`` method which takes :any:`tcod.console.Console` as a parameter and marks the player position on it.
-The parameters for ``on_draw`` are ``self`` because this is an instance method and ``console: tcod.console.Console``.
-``on_draw`` returns nothing, so be sure to add ``-> None``.
+The parameters for ``on_draw`` are ``self`` because this is an instance method and :python:`console: tcod.console.Console`.
+``on_draw`` returns nothing, so be sure to add :python:`-> None`.
 
 :any:`Console.print` is the simplest way to draw the player because other options would require bounds-checking.
-Call this method using the players current coordinates and the ``"@"`` character.
+Call this method using the players current coordinates and the :python:`"@"` character.
 
 .. code-block:: python
 
@@ -135,13 +137,13 @@ Call this method using the players current coordinates and the ``"@"`` character
             console.print(self.player_x, self.player_y, "@")
     ...
 
-Now remove the ``console.print(0, 0, "Hello World")`` line from ``main``.
+Now remove the :python:`console.print(0, 0, "Hello World")` line from ``main``.
 
 Before the context is made create a new ``ExampleState`` with player coordinates on the screen.
-Each :any:`Console` has ``.width`` and ``.height`` attributes which you can divide by 2 to get a centered coordinate for the player.
-Use Python's floor division operator ``//`` so that the resulting type is ``int``.
+Each :any:`Console` has :python:`.width` and :python:`.height` attributes which you can divide by 2 to get a centered coordinate for the player.
+Use Python's floor division operator :python:`//` so that the resulting type is :python:`int`.
 
-Modify the drawing routine so that the console is cleared, then passed to ``ExampleState.on_draw``, then passed to :any:`Context.present`.
+Modify the drawing routine so that the console is cleared, then passed to :python:`ExampleState.on_draw`, then passed to :any:`Context.present`.
 
 .. code-block:: python
     :emphasize-lines: 9,12-14
@@ -174,9 +176,9 @@ A new method will be added to the ``ExampleState`` for this called ``on_event``.
 Events are best handled using Python's `Structural Pattern Matching <https://peps.python.org/pep-0622/>`_.
 Consider reading `Python's Structural Pattern Matching Tutorial <https://peps.python.org/pep-0636/>`_.
 
-Begin matching with ``match event:``.
-The equivalent to ``if isinstance(event, tcod.event.Quit):`` is ``case tcod.event.Quit():``.
-Keyboard keys can be checked with ``case tcod.event.KeyDown(sym=tcod.event.KeySym.LEFT):``.
+Begin matching with :python:`match event:`.
+The equivalent to :python:`if isinstance(event, tcod.event.Quit):` is :python:`case tcod.event.Quit():`.
+Keyboard keys can be checked with :python:`case tcod.event.KeyDown(sym=tcod.event.KeySym.LEFT):`.
 Make a case for each arrow key: ``LEFT`` ``RIGHT`` ``UP`` ``DOWN`` and move the player in the direction of that key.
 See :any:`KeySym` for a list of all keys.