switch to sphinx

.github/workflows/deploy.yml

@@ -15,24 +15,18 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Install latest mdbook
-        run: |
-          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
-          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir mdbook
-          curl -sSL $url | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
-      - name: Build Book
+
+      - name: Build docs
         run: |
-          cd docs
-          mdbook build
+          python -m pip install alabaster==1.0.0 Sphinx==8.1.3
+          python -m sphinx docs/source docs/build
       - name: Setup Pages
         uses: actions/configure-pages@v4
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           # Upload entire repository
-          path: 'docs/book'
+          path: 'docs/build'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

docs/source/api/dme.rst

@@ -0,0 +1,84 @@
+:class:`DME` --- Code Reflection
+================================
+
+.. class:: DME
+
+   The :class:`DME` class provides reflection information for a BYOND project. This
+   includes looking up available types, proc and var names on those types, and
+   basic support for AST walking.
+
+   :class:`DME` instances are created with the following methods:
+
+   .. staticmethod:: from_file(filename: str | os.PathLike[str], parse_procs=False) -> DME
+
+      Read the BYOND environment from the *filename* referring to a ".dme" file.
+      If the optional *parse_procs* argument is :const:`True`, reflection data is
+      made available for all procs.
+
+   Once instantiated, the following methods are available:
+
+   .. method:: typesof(prefix: Path | str) -> list[Path]
+
+      Return a list of :class:`Path`\s which include the type *prefix* and any of
+      its subtypes.
+
+   .. method:: subtypesof(prefix: Path | str) -> list[Path]
+
+      Return a list of :class:`Path`\s of any subtypes of *prefix*, excluding
+      itself.
+
+   .. method:: walk_proc(path: Path | str, proc: str, walker)
+
+      Performs an AST walk of the proc *proc* on the object specified by *path*.
+      The argument *walker* is expected to be a Python object which exposes
+      methods for each kind of AST node you wish to visit. Each method should
+      take an argument *node*, which will be filled in with information about
+      that node in the AST. The currently available visitors are:
+
+      - ``visit_Break``
+      - ``visit_Call``
+      - ``visit_Constant``
+      - ``visit_Continue``
+      - ``visit_Crash``
+      - ``visit_Del``
+      - ``visit_DoWhile``
+      - ``visit_Expr``
+      - ``visit_For``
+      - ``visit_ForList``
+      - ``visit_ForRange``
+      - ``visit_If``
+      - ``visit_Label``
+      - ``visit_ParentCall``
+      - ``visit_Resource``
+      - ``visit_Return``
+      - ``visit_SelfCall``
+      - ``visit_Setting``
+      - ``visit_Spawn``
+      - ``visit_Switch``
+      - ``visit_Throw``
+      - ``visit_TryCatch``
+      - ``visit_Var``
+      - ``visit_While``
+
+      As with :class:`ast.NodeVisitor`, child nodes of a custom visitor method
+      will not be visited. There is currently no analogous ``generic_visit``
+      support.
+
+.. class:: TypeDecl
+
+   The :class:`TypeDecl` class returns basic information about a type declared
+   in the :class:`DME` file.
+
+   .. method:: proc_names() -> list[str]
+
+      Returns a list of proc names for the type declaration.
+
+   .. method:: var_names() -> list[str]
+
+      Returns a list of variables names for the type declaration. This does not
+      include variables declared in the type's parents.
+
+   .. method:: value(name: str)
+
+      Returns a Python representation of the variable *name*. This will lookup
+      values of variables declared in the type's parents.

docs/source/api/dmi.rst

@@ -0,0 +1,95 @@
+:class:`DMI` --- Icon Parsing
+=============================
+
+.. class:: DMI
+
+   The :class:`DMI` class provides the ability to parse and manipulate `.dmi`
+   files.
+
+   :class:`DMI` instances are created with the following methods:
+
+   .. staticmethod:: from_file(filename: str | os.PathLike[str]) -> DMI
+
+      Read the BYOND Icon file from the *filename* referring to a ".dmi" file.
+
+   Once instantiated, the following methods and properties are available:
+
+   .. property:: filepath
+      :type: pathlib.Path
+
+      The original path of the DMI file.
+
+   .. property:: icon_width
+      :type: int
+
+      The width of icons in the file.
+
+   .. property:: icon_height
+      :type: int
+
+      The height of icons in the file.
+
+   .. property:: icon_dims
+      :type: tuple[int, int]
+
+      The width and height of icons in the file.
+
+   .. method:: state_names() -> list[str]
+
+      Return a list of all state names in the icon file.
+
+   .. method:: state(name: str) -> IconState
+
+      Returns the :class:`IconState` with the given *name*.
+
+Individual icon states are represented by :class:`IconState`.
+
+.. class:: IconState
+
+   .. property:: name
+      :type: str
+
+      The name of the icon state. May not be unique within a file.
+
+   .. property:: frames
+      :type: int
+
+      The number of frames in the state.
+
+   .. property:: delays
+      :type: list[int]
+
+      A list of delays per frame, in ticks.
+
+   .. property:: dirs
+      :type: list[Dir]
+
+      A list of directions available in the icon state.
+
+   .. property:: movement
+      :type: bool
+
+      Whether the icon state is a movement state.
+
+   .. property:: rewind
+      :type: bool
+
+      Whether the icon state rewinds on animation.
+
+   .. method:: data_rgba8(frame: int, dir: Dir) -> bytes
+
+      Returns the image data for the given 1-indexed frame in RGBA8 bytes.
+
+      Using Pillow_, the image data for a given icon can quickly be turned into
+      a :mod:`PIL.Image` object and easily manipulated.
+
+      .. code-block:: python
+
+         from avulto import DMI, Dir
+         from PIL import Image
+         dmi = DMI.from_file("/SS13/icons/objects/weapons.dmi")
+         pistol = dmi.state("pistol")
+         data = pistol.data_rgba8(frame=1, dir=Dir.SOUTH)
+         image = Image.frombytes("RGBA", size=dmi.icon_dims, data=data)
+
+      .. _Pillow: https://pillow.readthedocs.io/en/stable/

docs/source/api/dmm.rst

@@ -0,0 +1,122 @@
+:class:`DMM` --- Map Processing and Manipulation
+================================================
+
+.. class:: DMM
+
+   The :class:`DMM` class provides an extensive API for reading and modifying
+   BYOND map files.
+
+   :class:`DMM` instances are created with the following methods:
+
+   .. staticmethod:: from_file(filename: str | os.PathLike[str])
+
+      Read the map file from the *filename* referring to a ".dmm" file.
+
+   Once instantiated, the following properties and methods are available:
+
+   .. property:: extents
+      :type: tuple[int, int, int]
+
+      The maximum size of the map's dimensions, i.e. width, length, and height.
+
+   .. property:: max_x
+      :type: int
+
+      The maximum X value of the map.
+
+   .. property:: max_y
+      :type: int
+
+      The maximum Y value of the map.
+
+   .. property:: max_z
+      :type: int
+
+      The maximum Z value of the map.
+
+   .. method:: tiledef(x: int, y: int, z: int) -> Tile
+
+      Returns the :class:`Tile` at the given coordinates.
+
+   .. method:: save_to(filename: str | os.PathLike[str])
+
+      Save the map into the file *filename*.
+
+   .. method:: coords()
+
+      Return an iterator over all possible 3D coordinates.
+
+   .. method:: tiles()
+
+      Return an iterator over all unique :class:`Tile`\s on the map.
+
+
+
+.. class:: Tile
+
+   :class:`Tile` objects returned from :func:`DMM.tiledef` can be read and
+   operated upon with the following methods.
+
+   .. NOTE::
+
+      Methods that modify tile prefabs currently apply to the preset, not the
+      individual tile. Future releases will hopefully provide a way to do both.
+
+   .. property:: area_path
+      :type: Path
+
+      Returns the tile's area.
+
+   .. property:: turf_path
+      :type: Path
+
+      Returns the tile's turf.
+
+   .. method:: convert() -> list[dict]
+
+      Returns a Python representation of all tile prefabs.
+
+   .. method:: find(prefix: str, exact=False) -> list[int]
+
+      Returns the indexes of all the prefabs on the tile with the given
+      *prefix*. If *exact* is :const:`True`, then the prefab path must
+      match exactly.
+
+   .. method:: only(prefix: str, exact=False) -> int | None
+
+      Returns the index of the only prefab with the given *prefix*, or
+      :const:`None` if no such prefab exists. Raises an error if there is more
+      than one prefab with the given *prefix*. If *exact* is :const:`True`, then
+      the prefab path must match exactly.
+
+   .. method:: prefab_path(index: int) -> Path
+
+      Returns the path of the prefab at *index*.
+
+   .. method:: prefab_vars(index: int) -> list[str]
+
+      Returns the list of var names for the varedits at *index*.
+
+   .. method:: prefab_var(index: int, name: str)
+
+      Returns a Python representation of the value of the var *name* at *index*.
+
+   .. method:: set_prefab_var(index: int, name: str, val)
+
+      Sets the value of the var *name* at *index* to *val*.
+
+   .. method:: set_path(index: int, path: Path | str)
+
+      Sets the path of the prefab at *index* to *path*, preserving any varedits.
+
+   .. method:: add_path(index: int, path: Path | str)
+
+      Adds a prefab with the given *path* at index *index*.
+
+   .. method:: del_prefab(index: int)
+
+      Deletes the prefab at *index*.
+
+   .. method:: del_prefab_var(index: int, name: str)
+
+      Deletes the varedit of the var *name* from the prefab at *index*.