Documentation updates

.gitignore

@@ -102,3 +102,4 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+.idea/

README.md

@@ -1,4 +1,20 @@
-# pytiled_parser
+# PyTiled Parser
-Python Library for parsing Tiled Map Editor maps.
 
-NOT READY FOR USE
+PyTiled Parser is a Python Library for parsing 
+[Tiled Map Editor](https://www.mapeditor.org/) (`.tmx`) files used to generate 
+maps and levels for 2D top-down or side-scrolling games.
+
+PyTiled Parser is not tied to any particular graphics library, and can be used
+with [Arcade](http://arcade.academy), 
+[Pyglet](https://pyglet.readthedocs.io/en/pyglet-1.3-maintenance/), 
+[Pygame](https://www.pygame.org/news), etc. 
+
+Documentation available at: https://pytiled-parser.readthedocs.io/
+
+The [Arcade](http://arcade.academy) library has 
+[supporting code](http://arcade.academy/arcade.html#module-arcade.tilemap) to 
+integrate PyTiled with that 2D libary, and 
+[example code](http://arcade.academy/examples/index.html#tmx-files-tiled-map-editor) showing its use.
+
+Original module by [Beefy-Swain](https://github.com/Beefy-Swain). 
+Contributions from [pvcraven](https://github.com/pvcraven).

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/api.rst

@@ -0,0 +1,23 @@
+.. _pytiled-api:
+
+PyTiled Parser API
+==================
+
+This page documents the Application Programming Interface (API)
+for the PyTiled Parser library.
+
+.. automodule:: pytiled_parser.xml_parser
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: pytiled_parser.objects
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: pytiled_parser.utilities
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

docs/source/conf.py

@@ -0,0 +1,51 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'PyTiled Parser'
+copyright = '2019, Beefy-Swain'
+author = 'Beefy-Swain'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,30 @@
+PyTiled Parser
+==============
+
+.. image:: 10_ladders_and_more.png
+    :width: 50%
+
+PyTiled Parser is a Python Library for parsing
+`Tiled Map Editor`_ (`.tmx`) files used to generate
+maps and levels for 2D top-down or side-scrolling games.
+
+PyTiled Parser is not tied to any particular graphics library, and can be used
+with Arcade_, Pyglet_, Pygame_, and more.
+
+API Documentation
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+
+Examples
+--------
+
+* `Games using the Arcade library <http://arcade.academy/examples/index.html#tmx-files-tiled-map-editor>`_
+
+.. _Tiled Map Editor: https://www.mapeditor.org/
+.. _Arcade: http://arcade.academy
+.. _Pyglet: https://pyglet.readthedocs.io/en/pyglet-1.3-maintenance/
+.. _Pygame: https://www.pygame.org/news

pytiled_parser/objects.py

@@ -10,7 +10,8 @@ import attr
 
 
 class Color(NamedTuple):
-    """Color object.
+    """
+    Color object.
 
     Attributes:
         red (int): Red, between 1 and 255.
@@ -68,7 +69,8 @@ class Template:
 
 @attr.s(auto_attribs=True)
 class Chunk:
-    """Chunk object for infinite maps.
+    """
+    Chunk object for infinite maps.
 
     See: https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#chunk
 
@@ -76,8 +78,7 @@ class Chunk:
         location (OrderedPair): Location of chunk in tiles.
         width (int): The width of the chunk in tiles.
         height (int): The height of the chunk in tiles.
-        layer_data (List[List(int)]): The global tile IDs in chunky
+        layer_data (List[List(int)]): The global tile IDs in chunky according to row.
-            according to row.
     """
 
     location: OrderedPair
@@ -88,17 +89,15 @@ class Chunk:
 
 @attr.s(auto_attribs=True)
 class Image:
-    """Image object.
+    """
+    Image object.
 
     This module does not support embedded data in image elements.
 
     Attributes:
-        source (Optional[str]): The reference to the tileset image file.
+        source (Optional[str]): The reference to the tileset image file. Note that this is a relative path compared to FIXME
-            Not that this is a relative path compared to FIXME
+        trans (Optional[Color]): Defines a specific color that is treated as transparent.
-        trans (Optional[Color]): Defines a specific color that is treated
+        width (Optional[str]): The image width in pixels (optional, used for tile index correction when the image changes).
-            as transparent.
-        width (Optional[str]): The image width in pixels
-            (optional, used for tile index correction when the image changes).
         height (Optional[str]): The image height in pixels (optional).
     """
 
@@ -128,8 +127,7 @@ class Terrain(NamedTuple):
 
     Args:
         name (str): The name of the terrain type.
-        tile (int): The local tile-id of the tile that represents the
+        tile (int): The local tile-id of the tile that represents the terrain visually.
-            terrain visually.
     """
 
     name: str
@@ -174,25 +172,26 @@ class TileTerrain:
 
 @attr.s(auto_attribs=True, kw_only=True)
 class Layer:
-    """Class that all layers inherret from.
+    """
+    Class that all layers inherit from.
 
     Args:
-        id: Unique ID of the layer. Each layer that added to a map gets a
+        id: Unique ID of the layer. Each layer that added to a map gets a \
-            unique id. Even if a layer is deleted, no layer ever gets the same
+            unique id. Even if a layer is deleted, no layer ever gets the same \
             ID.
         name: The name of the layer object.
         tiled_objects: List of tiled_objects in the layer.
         offset: Rendering offset of the layer object in pixels.
-        opacity: Decimal value between 0 and 1 to determine opacity. 1 is
+        opacity: Decimal value between 0 and 1 to determine opacity. 1 is \
-            completely opaque, 0 is completely transparent.
+                 completely opaque, 0 is completely transparent.
         properties: Properties for the layer.
         color: The color used to display the objects in this group.
-            FIXME: editor only?
+        draworder: Whether the objects are drawn according to the order of the \
-        draworder: Whether the objects are drawn according to the order of the
+                   object elements in the object group element ('manual'), or sorted \
-            object elements in the object group element ('manual'), or sorted
+                   by their y-coordinate ('topdown'). Defaults to 'topdown'. See: \
-            by their y-coordinate ('topdown'). Defaults to 'topdown'. See:
+                   https://doc.mapeditor.org/en/stable/manual/objects/#changing-stacking-order \
-            https://doc.mapeditor.org/en/stable/manual/objects/#changing-stacking-order
+                   for more info.
-            for more info.
+
     """
 
     id_: int
@@ -237,15 +236,13 @@ class TiledObject:
         https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#object
 
     Args:
-        id_ (int): Unique ID of the object. Each object that is placed on a
+        id (int): Unique ID of the object. Each object that is placed on a \
-            map gets a unique id. Even if an object was deleted, no object
+           map gets a unique id. Even if an object was deleted, no object \
-            gets the same ID.
+           gets the same ID.
         gid (Optional[int]): Global tiled object ID
         location (OrderedPair): The location of the object in pixels.
-        size (Size): The width of the object in pixels
+        size (Size): The width of the object in pixels (default: (0, 0)).
-            (default: (0, 0)).
+        rotation (int): The rotation of the object in degrees clockwise (default: 0).
-        rotation (int): The rotation of the object in degrees clockwise
-            (default: 0).
         opacity (int): The opacity of the object. (default: 255)
         name (Optional[str]): The name of the object.
         type (Optional[str]): The type of the object.
@@ -374,7 +371,8 @@ class TextObject(TiledObject):
 
 @attr.s(auto_attribs=True, kw_only=True)
 class ObjectLayer(Layer):
-    """TiledObject Group Object.
+    """
+    TiledObject Group Object.
 
     The object group is in fact a map layer, and is hence called \
     "object layer" in Tiled.
@@ -385,13 +383,13 @@ class ObjectLayer(Layer):
     Args:
         tiled_objects: List of tiled_objects in the layer.
         offset: Rendering offset of the layer object in pixels.
-        color: The color used to display the objects in this group.
+        color: The color used to display the objects in this group. FIXME: editor only?
-            FIXME: editor only?
+        draworder: Whether the objects are drawn according to the order of the \
-        draworder: Whether the objects are drawn according to the order of the
+                   object elements in the object group element ('manual'), or sorted \
-            object elements in the object group element ('manual'), or sorted
+                   by their y-coordinate ('topdown'). Defaults to 'topdown'. See: \
-            by their y-coordinate ('topdown'). Defaults to 'topdown'. See:
+                   https://doc.mapeditor.org/en/stable/manual/objects/#changing-stacking-order \
-            https://doc.mapeditor.org/en/stable/manual/objects/#changing-stacking-order
+                   for more info.
-            for more info.
+
     """
 
     tiled_objects: List[TiledObject]
@@ -425,26 +423,25 @@ class TileSet:
 
     Args:
         name (str): The name of this tileset.
-        max_tile_size (Size): The maximum size of a tile in this
+        max_tile_size (Size): The maximum size of a tile in this tile set in pixels.
-            tile set in pixels.
+        spacing (int): The spacing in pixels between the tiles in this \
-        spacing (int): The spacing in pixels between the tiles in this
             tileset (applies to the tileset image).
-        margin (int): The margin around the tiles in this tileset
+        margin (int): The margin around the tiles in this tileset \
             (applies to the tileset image).
         tile_count (int): The number of tiles in this tileset.
-        columns (int): The number of tile columns in the tileset.
+        columns (int): The number of tile columns in the tileset. \
-            For image collection tilesets it is editable and is used when
+            For image collection tilesets it is editable and is used when \
             displaying the tileset.
-        grid (Grid): Only used in case of isometric orientation, and
+        grid (Grid): Only used in case of isometric orientation, and \
-            determines how tile overlays for terrain and collision information
+            determines how tile overlays for terrain and collision information \
             are rendered.
-        tileoffset (Optional[OrderedPair]): Used to specify an offset in
+        tileoffset (Optional[OrderedPair]): Used to specify an offset in \
-            pixels when drawing a tile from the tileset. When not present, no
+            pixels when drawing a tile from the tileset. When not present, no \
             offset is applied.
         image (Image): Used for spritesheet tile sets.
-        terrain_types (Dict[str, int]): List of of terrain types which
+        terrain_types (Dict[str, int]): List of of terrain types which \
-            can be referenced from the terrain attribute of the tile object.
+            can be referenced from the terrain attribute of the tile object. \
-            Ordered according to the terrain element's appearance in the TSX
+            Ordered according to the terrain element's appearance in the TSX \
             file.
         tiles (Optional[Dict[int, Tile]]): Dict of Tile objects by Tile.id.
     """

pytiled_parser/utilities.py

@@ -60,8 +60,7 @@ def get_tile_by_gid(
 
     Returns:
         objects.Tile: The Tile object reffered to by the global tile ID.
-        None: If there is no objects.Tile object in the tile_set.tiles dict
+        None: If there is no objects.Tile object in the tile_set.tiles dict for the associated gid.
-            for the associated gid.
     """
     tile_set_key = _get_tile_set_key(gid, list(tile_sets.keys()))
     tile_set = tile_sets[tile_set_key]