Documentation for first public release.

README.rst

@@ -0,0 +1,79 @@
+Minetest Craft Recipe Conflict Detector
+----------------------------------------
+
+
+[Minetest](https://www.minetest.net/) mods sometimes define the same craft
+recipe for different items.  If conflicting recipes are installed on the same
+server, some game items will be impossible to craft.  Minetest administrators
+can use the detector to identify conflicts, making it easy to reconcile them
+before players are affected.
+
+This is a command line tool intended for server administrators.  In order to use
+it, as well as to do anything with the information in provides, you'll need to
+be:
+
+1. Comfortable understanding and running commands in the
+terminal.
+2. Prepared to edit plain-text and Minetest recipe code files as needed.
+
+Setup
+-----
+
+
+Linux (should be similar for Mac)
+=================================
+
+Linux, command line:
+
+.. code:: bash
+     
+    $ pip install --user vex  
+        # vex is like virtualenv, but with Unix elegance:
+        # https://pypi.python.org/pypi/vex
+    $ vex --python python3 -m minetest_recipe
+    $ git clone git+git://github.com/ptvirgo/mt_recipe_conflict_detector
+    $ cd mt_recipe_conflict_checker
+    $ pip install ./
+    $ cp -r recipe_export ~/.minetest/mods
+
+
+Windows
+=======
+
+I haven't used Windows in over 15 years; if someone wants to sort these out I'm
+willing to add instructions here.
+
+
+Running
+-------
+
+- Activate the **recipe_export** mod along with any mods you wish to detect
+conflicts for to a Minetest world: named *MyWorld* for this example.
+- Start up the Minetest game with your demo world to load the recipes.
+- Shut down the game to export them.
+- Run 
+
+.. code:: bash
+    vex minetest_recipe scripts/detect_conflicts.py ~/.minetest/worlds/MyWorld/recipe_export.json
+
+
+Results
+=======
+
+If you're very, very lucky, there will be no output at all.  Congrats!  No
+conflicts.
+
+More likely, you'll see a list of conflicts similar to this sample:
+
+::
+    katanas:katana_wood conflicts with katanas:umad_bro
+    default:furnace conflicts with xdecor:stone_rune
+    "gates_wooden:classic" conflicts with doors:gate_wood_closed
+    itemframes:frame conflicts with frame:empty
+    ...
+
+In the example above, an admin would likely want to remove or alter the recipe
+for the fictional "katanas:umad_bro" item, as well as the rest of them.
+
+If a line appears stating that a recipe conflicts with itself, that means the
+same recipe is being loaded by your server twice.

docs/dev_notes.st

@@ -0,0 +1,48 @@
+Developer notes
+---------------
+
+
+Lingo / Data definitions
+========================
+
+For the purposes of the code, I adopted the following lingo.  Based as best as I
+could on existing, documented terms.
+
+CraftItem
+    A string representation of a single, specific item as can be used in the Minetest inventory or craft table.
+
+    - None or an empty string can represent a CraftItem
+    - Validators should convert empty strings to None
+    - CraftItems may appear with a leading ":", which should be removed for our purposes.
+    - *Examples:* "default:steel_ingot" or "default:diamond"
+
+GroupName
+    A string representation of a named collection of Minetest Craftitems.
+
+    - The string must lead with the characters "group:"
+    - *Examples:* "group:stick" or "group:wood"
+
+Group
+    A python set containing CraftItems
+
+    - Groups should not contain the empty string or None
+    - Groups should reflect the set of Items expected per their related GroupName
+    - *Example:* {"default:steel_ingot, "default:diamond"}
+
+Item
+    Craft be a CraftItem, Group, or None.
+
+RecipeCollection
+    May be:
+
+    - an Item
+    - a list of up to 9 Items
+    - a list containing up to 3 lists of up to 3 items, ie:
+      [[Item, Item, Item], [Item, Item, Item], [Item, Item, Item]]
+
+CraftType
+    A string representing the "kind" of a given Recipe, per the Minetest game.
+
+    - "shaped", "shapeless", "fuel", and "cooking" are standard.
+    - "shaped" is the default.
+    - Other CraftType strings may be introduced by Minetest mods.

mt_crafting_recipe/core.py

@@ -1,43 +1,4 @@
 # -*- coding: utf-8 -*-
-"""Lingo / Data definitions
-
-A CraftItem is a string representation of a single, specific item as can be
-used in the Minetest inventory or craft table.
-None or an empty string can represent a CraftItem
-Validators should convert empty strings to None
-CraftItems may appear with a leading ":", which should be removed for our
-purposes.
-
-Examples: "default:steel_ingot" or "default:diamond"
-
-A GroupName is a string representation of a named collection of Minetest
-Craftitems.
-The string must lead with the characters "group:"
-Examples: "group:stick" or "group:wood"
-
-A Group is a python set of CraftItems
-Groups should not contain the empty string or None
-Groups should reflect the set of Items expected per their related GroupName
-Example: {"default:steel_ingot, "default:diamond"}
-
-An Item can be a CraftItem, Group, or None. It may not be GroupName.
-
-A RecipeCollection may be:
-    - an Item
-    - a list of up to 9 Items
-    - a list containing up to 3 lists of up to 3 items, ie:
-      [[Item, Item, Item], [Item, Item, Item], [Item, Item, Item]]
-
-A CraftType is a string representing the "kind" of a given Recipe, per the
-Minetest game.
-"shaped", "shapeless", "fuel", and "cooking" are standard.
-"shaped" is the default.
-Other CraftType strings may be introduced by Minetest mods.
-
-Objects
--------
-"""
-
 from . import helpers
 
 

setup.py

@@ -4,10 +4,11 @@
 from setuptools import setup
 
 setup(
-    name="Minetest Crafting Recipe",
+    name="mt_crafting_recipe",
     description="Minetest recipe conflict detector",
     author="Pablo Virgo",
     author_email="mailbox@pablovirgo.com",
+    url="https://github.com/ptvirgo/mt_recipe_conflict_detector",
     version="0.1.1",
     packages=["mt_crafting_recipe"],
     scripts=["scripts/detect_conflicts.py"]