From 630ce519a1cc3ff3b73f966e6e1a9e56c5e27278 Mon Sep 17 00:00:00 2001
From: Mark Wolfman <canismarko@gmail.com>
Date: Sun, 20 Mar 2022 11:37:30 -0500
Subject: [PATCH] Added instructions for running tests and building docs.

---
 CONTRIBUTING.rst      | 64 +++++++++++++++++++++++++++++++++++++++++++
 docs/contributing.rst |  2 ++
 docs/index.rst        |  1 +
 tests/test_dice.py    |  1 +
 4 files changed, 68 insertions(+)
 create mode 100644 docs/contributing.rst

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index ce85c1d..c26fc42 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -78,6 +78,70 @@ IP violations.
 How to Contribute
 =================
 
+Running Tests
+-------------
+
+Dungeonsheets uses tests to verify the package works as
+intended. Tests are found in the ``tests/`` folder. To run the tests
+using *pytest*, run the following from a console:
+
+.. code:: bash
+
+	  pip install -r requirements.txt -r requirements-tests.txt
+	  pytest
+
+Dungeonsheets defines tests using the *unittest* package in the
+standard library. **For example**, to test a new function in the
+``dungeonsheets/dice.py`` module, modify ``tests/test_dice.py``:
+
+.. code-block:: python
+   :caption: dice.py
+
+   def roll(a, b=None):
+       """roll(20) means roll 1d20, roll(2, 6) means roll 2d6"""
+       if b is None:
+           return random.randint(1, a)
+       else:
+           return sum([random.randint(1, b) for _ in range(a)])
+
+.. code-block:: python
+   :caption: test_dice.py
+
+    from unittest import TestCase
+    from dungeonsheets.dice import roll
+
+    class TestDice(TestCase):
+        def test_simple_rolling(self):
+            num_tests = 100
+            # Do a bunch of rolls and make sure the numbers are within the requsted range
+            for _ in range(num_tests):
+                result = roll(6)
+                self.assertGreaterEqual(result, 1)
+                self.assertLessEqual(result, 6)
+
+        def test_multi_rolling(self):
+            num_tests = 100
+            for _ in range(num_tests):
+                result = roll(2, 4)  # Roll 2d4
+                self.assertGreaterEqual(result, 2)
+                self.assertLessEqual(result, 8)
+
+
+Building Documentation
+----------------------
+
+Dungeonsheets uses sphinx to build documentations. All files are in
+reStructuredText and are kept in the ``docs/`` folder. To build the
+HTML files, run:
+
+.. code:: bash
+
+	  pip install -r requirements.txt -r requirements-tests.txt
+	  cd docs/
+	  make html
+
+The results can be found in the ``_build/html/`` foler.
+
 Submitting Bugs
 ---------------
 
diff --git a/docs/contributing.rst b/docs/contributing.rst
new file mode 100644
index 0000000..89d0049
--- /dev/null
+++ b/docs/contributing.rst
@@ -0,0 +1,2 @@
+.. include:: ../CONTRIBUTING.rst
+
diff --git a/docs/index.rst b/docs/index.rst
index 411c144..c622c03 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Welcome to Dungeonsheets's documentation!
    gm_notes
    advanced_features
    examples
+   contributing
 
 Indices and tables
 ==================
diff --git a/tests/test_dice.py b/tests/test_dice.py
index 10910a8..99cbe07 100644
--- a/tests/test_dice.py
+++ b/tests/test_dice.py
@@ -26,6 +26,7 @@ class TestDice(TestCase):
 
     def test_simple_rolling(self):
         num_tests = 100
+        # Do a bunch of rolls and make sure the numbers are within the requsted range
         for _ in range(num_tests):
             result = roll(6)
             self.assertGreaterEqual(result, 1)