Added debugging page

docs/build/_sources/debugging.txt

@@ -0,0 +1,35 @@
+**Debugging diceroll**
+=======================
+**diceroll 2.2** keeps a log file of any dice rolls made during its last run. You will find ``diceroll.log`` in the ``Logs``
+folder it creates if one isn't there already. In the file you will see mentions of dice being rolled. **diceroll** uses
+a default logging mode of ``INFO`` which isn't that verbose. ::
+
+   module_log.setLevel(logging.INFO)
+
+   Sun, 01 Oct 2017 16:08:03 INFO diceroll - Logging started.
+   Sun, 01 Oct 2017 16:08:03 INFO diceroll - roll() v2.2 started, and running...
+   Sun, 01 Oct 2017 16:08:03 INFO diceroll - 3D4 = 3D4+0 = 10
+
+Changing **diceroll's** logging mode to ``DEBUG`` will record debugging messages in the ``Logs\diceroll.log`` file. ::
+
+   module_log.setLevel(logging.DEBUG)
+
+   Sun, 01 Oct 2017 16:27:21 INFO diceroll - Logging started.
+   Sun, 01 Oct 2017 16:27:21 INFO diceroll - roll() v2.2 started, and running...
+   Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Asked to roll 3D4:
+   Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Using three 4-sided dice...
+   Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Rolled a 4
+   Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Rolled a 2
+   Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Rolled a 2
+   Sun, 01 Oct 2017 16:27:21 INFO diceroll - 3D4 = 3D4+0 = 8
+
+.. note::
+   Running **diceroll** in ``DEBUG`` mode may create a log while that will be too huge to open. A program of yours
+   left running for a long period of time could create millions of lines of recorded log entries. Fortunately, ``diceroll.log`` is
+   reset each time your program is run. Also, any errors encountered will be recorded as ``ERROR`` in the log file, no
+   matter which logging mode you've chosen to use.
+
+If your own code has logging enabled for it, be sure to let **diceroll** know by changing ``your_code_name_here`` to
+the name of the program you're calling ``roll()`` from. ::
+
+   log = logging.getLogger('your_code_name_here.diceroll')

docs/build/_sources/designers_notes.txt

@@ -23,17 +23,17 @@ C language used to write Python had very robust random number generators.
 And because Python was written in C, it just made sense for it to make
 use of C libraries.
 
-For those that are curious, *diceroll* uses the ``random.randint()`` module that comes
+For those that are curious, **diceroll** uses the ``random.randint()`` module that comes
 with CPython. There are stronger random generators out there now, with NumPy being one
-of them. But at the time of designing *diceroll*, I didn't quite understand how-all
+of them. But at the time of designing **diceroll**, I didn't quite understand how-all
 NumPy worked, or what version of it to install. And for rolling dice, the built-in
 random number generator would be just fine.
 
 Lessons Learned
 ---------------
 In the past, when I needed a random number from 1 to say 6 (see 6-sided dice), I would use ``INT(RND(1)*6) + 1``.
 And I would be used to doing it that way for probably 15 years or so, because that is
-how most BASIC languages did things. Other languages like C required me to wip out the
+how most BASIC languages did things. Other languages like C required me to whip out the
 80286 System Developer's 3-ring binder to find out how ``srand()`` and ``rand()`` worked,
 and under what circumstances.
 
@@ -64,7 +64,7 @@ Which looked a bit cleaner. But I was debating if I wanted to use ``randint()``
 my normal coding.
 
 So while I was learning how to write my own functions, as well as how to go about importing them, I came up with
-an idea for *diceroll*. It would included a ``roll()`` function, and a ``die_rolls()`` function as
+an idea for **diceroll**. It would included a ``roll()`` function, and a ``die_rolls()`` function as
 a "side effect." Even though ``die_rolls()`` had no error-checking, ``roll()`` would call it after
 doing its own error-checking.
 
@@ -88,8 +88,8 @@ code. And the simple addition or subtraction of DMs to such a roll was making th
 
 The Channel 1
 -------------
-*diceroll* was written years ago. It gets looked at by GitHub visitors who Google by now and again. But not
-many will use this module because of the simple fact that Python is now version 3.6+ something. So *diceroll*, along
+**diceroll** was written years ago. It gets looked at by GitHub visitors who Google by now and again. But not
+many will use this module because of the simple fact that Python is now version 3.6+ something. So **diceroll**, along
 with a slew of other pre-Python 2.6 era modules, are the Channel 1 stations in the room that no TV can possibly watch.
 
 It really comes down to a philosophy. I waited on learning Python until a version was released where I could say,
@@ -105,7 +105,7 @@ Python is trying to be all things to all programmers these days. And it has beco
 I am not a functional programmer. Never have been. But a lot of people are. And Python now serves them very well.
 I'm often told, *"Python now does things this way."* But it is ways that I don't see myself using.
 
-People are altering *diceroll* so that it works in their Python, just as I am altering their uploaded code so that it
+People are altering **diceroll** so that it works in their Python, just as I am altering their uploaded code so that it
 works in my Python. If I wanted my code to reach more people, of course I would have to program using
 the latest greatest Python. But there is a certain individuality lost in doing that.
 
@@ -114,7 +114,7 @@ it grows. And doesn't split the party as it grows.
 
 Getting Sphinxed
 ----------------
-With the release of *diceroll 2.2*, I wanted to learn something new in regards to Python. Even though I use 2.5.4,
+With the release of **diceroll 2.2**, I wanted to learn something new in regards to Python. Even though I use 2.5.4,
 there is still a lot about it that I have never delved into. Sphinx was something I had not really paid any mind to
 in the past. It was yet another one of those *need to know only* things about Python. Some things I'd get around to
 learning only when I had to, but only if it was part of something else that I have taken an interest in doing.

docs/build/_sources/diceroll.txt

@@ -1,5 +1,5 @@
-**diceroll Module**
-===================
+**The diceroll Module**
+=======================
 
 .. automodule:: diceroll
    :members:

docs/build/_sources/index.txt

@@ -11,10 +11,10 @@ Requirements
 ------------
 
 * **Microsoft Windows**
-       *diceroll* has been tested on Windows versions: XP, 7, 8, and 10.
+       **diceroll** has been tested on Windows versions: XP, 7, 8, and 10.
        It has not been tested on MacOS or Linux.
 * **Python 2.5**
-       *diceroll* was written using the C implementation of Python
+       **diceroll** was written using the C implementation of Python
        version 2.5.4. Also known as CPython. With some doing, this
        module could of course be re-written for Jython, PyPy, or
        IronPython.
@@ -23,7 +23,7 @@ Requirements
        running this module.
 
 .. Warning::
-   *diceroll* will not work with **Python 2.6+**.
+   **diceroll** will not work with **Python 2.6+**.
 
 
 
@@ -37,6 +37,7 @@ Contents
    installing
    tutorial
    diceroll
+   debugging
 
 Indices and Tables
 ------------------

docs/build/_sources/installing.txt

@@ -1,6 +1,6 @@
 **Installing diceroll**
 =======================
-Installing *diceroll 2.2* is as easy as always. Just copy ``diceroll.py`` into the same folder
+Installing **diceroll 2.2** is as easy as always. Just copy ``diceroll.py`` into the same folder
 your code happens to be in.
 
 Then add this line at (or near) the top of your code: ::

docs/build/_sources/tutorial.txt

@@ -1,5 +1,8 @@
 **diceroll Tutorial**
 =====================
+
+Rolling the Dice
+----------------
 Once ``diceroll.py`` is installed and recognized by your code, its ``roll()`` function can be used right away. This
 function returns an integer, by the way. So it can be used as any other integer would be used. But first,
 we must give this function a value to work from.
@@ -23,7 +26,7 @@ The dice types to roll are:
    standard notation for dice rolls used in games. But each game typically uses its own notation.
 
    |
-   | *diceroll* uses a simple standard when it comes to the more plainer dice types.
+   | **diceroll** uses a simple standard when it comes to the more plainer dice types.
    |
    | Some examples are:
    |
@@ -37,7 +40,9 @@ The dice types to roll are:
    | roll('4D4-4') -- add -4 DM to roll
    | roll('2DD+3') -- roll (2D6+3) x 10
    | roll('info') -- release version of program
-
+
+Encountering Errors
+-------------------
 Entering an invalid string for ``roll()`` will return an error message, as well as a value of 0 from the function. ::
 
    print roll('3d')
@@ -48,10 +53,12 @@ Entering an invalid string for ``roll()`` will return an error message, as well
    |
    | 0
 
-One exception to the "integer" rule for ``roll()`` is when using ``roll('info')``, which will return two strings.
-
+What's New
+----------
 .. versionadded:: 2.2
 
+One exception to the "integer" rule for ``roll()`` is when using ``roll('info')``, which will return two strings.
+
 >>> version, release = roll('info')
 >>> print version
 2.2

docs/build/debugging.html

@@ -0,0 +1,124 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Debugging diceroll &mdash; diceroll 2.2 Manual</title>
+    <link rel="stylesheet" href="_static/default.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+          URL_ROOT:    '',
+          VERSION:     '2.2.1b',
+          COLLAPSE_MODINDEX: false,
+          FILE_SUFFIX: '.html'
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <link rel="shortcut icon" href="_static/diceroll_icon_16x16.ico"/>
+    <link rel="contents" title="Global table of contents" href="contents.html" />
+    <link rel="index" title="Global index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="top" title="diceroll 2.2 Manual" href="index.html" />
+    <link rel="prev" title="The diceroll Module" href="diceroll.html" />
+  </head>
+  <body>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="modindex.html" title="Global Module Index"
+             accesskey="M">modules</a> |</li>
+        <li class="right" >
+          <a href="diceroll.html" title="The diceroll Module"
+             accesskey="P">previous</a> |</li>
+        <li><a href="index.html">diceroll 2.2 Manual</a> &raquo;</li>
+      </ul>
+    </div>
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body">
+
+
+  <div class="section" id="debugging-diceroll">
+<h1><strong>Debugging diceroll</strong><a class="headerlink" href="#debugging-diceroll" title="Permalink to this headline">¶</a></h1>
+<p><strong>diceroll 2.2</strong> keeps a log file of any dice rolls made during its last run. You will find <tt class="docutils literal"><span class="pre">diceroll.log</span></tt> in the <tt class="docutils literal"><span class="pre">Logs</span></tt>
+folder it creates if one isn&#8217;t there already. In the file you will see mentions of dice being rolled. <strong>diceroll</strong> uses
+a default logging mode of <tt class="docutils literal"><span class="pre">INFO</span></tt> which isn&#8217;t that verbose.</p>
+<pre>module_log.setLevel(logging.INFO)
+
+Sun, 01 Oct 2017 16:08:03 INFO diceroll - Logging started.
+Sun, 01 Oct 2017 16:08:03 INFO diceroll - roll() v2.2 started, and running...
+Sun, 01 Oct 2017 16:08:03 INFO diceroll - 3D4 = 3D4+0 = 10</pre>
+<p>Changing <strong>diceroll&#8217;s</strong> logging mode to <tt class="docutils literal"><span class="pre">DEBUG</span></tt> will record debugging messages in the <tt class="docutils literal"><span class="pre">Logs\diceroll.log</span></tt> file.</p>
+<pre>module_log.setLevel(logging.DEBUG)
+
+Sun, 01 Oct 2017 16:27:21 INFO diceroll - Logging started.
+Sun, 01 Oct 2017 16:27:21 INFO diceroll - roll() v2.2 started, and running...
+Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Asked to roll 3D4:
+Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Using three 4-sided dice...
+Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Rolled a 4
+Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Rolled a 2
+Sun, 01 Oct 2017 16:27:21 DEBUG diceroll - Rolled a 2
+Sun, 01 Oct 2017 16:27:21 INFO diceroll - 3D4 = 3D4+0 = 8</pre>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Running <strong>diceroll</strong> in <tt class="docutils literal"><span class="pre">DEBUG</span></tt> mode may create a log while that will be too huge to open. A program of yours
+left running for a long period of time could create millions of lines of recorded log entries. Fortunately, <tt class="docutils literal"><span class="pre">diceroll.log</span></tt> is
+reset each time your program is run. Also, any errors encountered will be recorded as <tt class="docutils literal"><span class="pre">ERROR</span></tt> in the log file, no
+matter which logging mode you&#8217;ve chosen to use.</p>
+</div>
+<p>If your own code has logging enabled for it, be sure to let <strong>diceroll</strong> know by changing <tt class="docutils literal"><span class="pre">your_code_name_here</span></tt> to
+the name of the program you&#8217;re calling <tt class="docutils literal"><span class="pre">roll()</span></tt> from.</p>
+<div class="highlight"><pre><span class="n">log</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s">&#39;your_code_name_here.diceroll&#39;</span><span class="p">)</span>
+</pre></div>
+</div>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+            <h4>Previous topic</h4>
+            <p class="topless"><a href="diceroll.html" title="previous chapter"><strong>The diceroll Module</strong></a></p>
+            <h3>This Page</h3>
+            <ul class="this-page-menu">
+              <li><a href="_sources/debugging.txt">Show Source</a></li>
+            </ul>
+            <h3>Quick search</h3>
+            <form class="search" action="search.html" method="get">
+              <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
+              <input type="hidden" name="check_keywords" value="yes" />
+              <input type="hidden" name="area" value="default" />
+            </form>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="modindex.html" title="Global Module Index"
+             accesskey="M">modules</a> |</li>
+        <li class="right" >
+          <a href="diceroll.html" title="The diceroll Module"
+             accesskey="P">previous</a> |</li>
+        <li><a href="index.html">diceroll 2.2 Manual</a> &raquo;</li>
+      </ul>
+    </div>
+    <div class="footer">
+      &copy; Copyright 2017, Shawn Driscoll.
+      Last updated on Oct 01, 2017.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
+    </div>
+  </body>
+</html>