Merge pull request #3 from sommersoft/new_docs

Improve Ref Docs

Author: kattni

readthedocs.yml renamed to .readthedocs.yml

@@ -16,15 +16,17 @@ deploy:
   provider: releases
   api_key: $GITHUB_TOKEN
   file_glob: true
-  file: bundles/*
+  file: $TRAVIS_BUILD_DIR/bundles/*
   skip_cleanup: true
+  overwrite: true
   on:
     tags: true
 
 install:
-  - pip install pylint circuitpython-build-tools
+  - pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme
 
 script:
   - pylint --disable=missing-docstring adafruit_thermal_printer/*.py
   - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
   - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-thermal-printer --library_location .
+  - cd docs && sphinx-build -E -W -b html . _build/html

.travis.yml

@@ -10,6 +10,10 @@ Introduction
     :target: https://discord.gg/nBQh6qu
     :alt: Discord
 
+.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_Thermal_Printer.svg?branch=master
+    :target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_Thermal_Printer
+    :alt: Build Status
+
 CircuitPython module for control of various small serial thermal printers.
 
 Dependencies
@@ -25,15 +29,7 @@ This is easily achieved by downloading
 Usage Example
 =============
 
-See examples/simpletest.py for a demo of basic printer usage.
-
-API Reference
-=============
-
-.. toctree::
-   :maxdepth: 2
-
-   api
+See examples/thermal_printer_simpletest.py for a demo of basic printer usage.
 
 Contributing
 ============
@@ -65,3 +61,26 @@ Then run the build:
 .. code-block:: shell
 
     circuitpython-build-bundles --filename_prefix adafruit_circuitpython_thermal_printer --library_location .
+
+Sphinx documentation
+-----------------------
+
+Sphinx is used to build the documentation based on rST files and comments in the code. First,
+install dependencies (feel free to reuse the virtual environment from above):
+
+.. code-block:: shell
+
+    python3 -m venv .env
+    source .env/bin/activate
+    pip install Sphinx sphinx-rtd-theme
+
+Now, once you have the virtual environment activated:
+
+.. code-block:: shell
+
+    cd docs
+    sphinx-build -E -W -b html . _build/html
+
+This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
+view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
+locally verify it will pass.

README.rst

@@ -20,18 +20,33 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_thermal_printer`
-====================================================
+`adafruit_thermal_printer.thermal_printer` - Thermal Printer Driver
+=====================================================================
 
 Thermal printer control module built to work with small serial thermal
 receipt printers.  Note that these printers have many different firmware
 versions and care must be taken to select the appropriate module inside this
 package for your firmware printer:
-  - thermal_printer = The latest printers with firmware version 2.68+
-  - thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
-  - thermal_printer_legacy = Printers with firmware version before 2.64.
+
+* thermal_printer = The latest printers with firmware version 2.68+
+* thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
+* thermal_printer_legacy = Printers with firmware version before 2.64.
 
 * Author(s): Tony DiCola
+
+Implementation Notes
+--------------------
+
+**Hardware:**
+
+* Mini `Thermal Receipt Printer
+  <https://www.adafruit.com/product/597>`_ (Product ID: 597)
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
+  https://github.com/adafruit/circuitpython/releases
+
 """
 import time
 
@@ -319,7 +334,8 @@ def _print_bitmap(self, width, height, data):
         pre-process your images with a script, you CANNOT send .jpg/.bmp/etc.
         image formats.  See this Processing sketch for preprocessing:
         https://github.com/adafruit/Adafruit-Thermal-Printer-Library/blob/master/processing/bitmapImageConvert/bitmapImageConvert.pde
-        NOTE: This is currently not working because it appears the bytes are
+
+        .. note:: This is currently not working because it appears the bytes are
         sent too slowly and the printer gets confused with not enough data being
         sent to it in the expected time.
         """

adafruit_thermal_printer/thermal_printer.py

@@ -20,16 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_thermal_printer_264`
-====================================================
+`adafruit_thermal_printer.thermal_printer_264.ThermalPrinter`
+==============================================================
 
 Thermal printer control module built to work with small serial thermal
 receipt printers.  Note that these printers have many different firmware
 versions and care must be taken to select the appropriate module inside this
 package for your firmware printer:
-  - thermal_printer = The latest printers with firmware version 2.68+
-  - thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
-  - thermal_printer_legacy = Printers with firmware version before 2.64.
+
+* thermal_printer = The latest printers with firmware version 2.68+
+* thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
+* thermal_printer_legacy = Printers with firmware version before 2.64.
 
 * Author(s): Tony DiCola
 """

adafruit_thermal_printer/thermal_printer_264.py

@@ -20,16 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_thermal_printer_legacy`
-====================================================
+`adafruit_thermal_printer.thermal_printer_legacy.ThermalPrinter`
+=================================================================
 
 Thermal printer control module built to work with small serial thermal
 receipt printers.  Note that these printers have many different firmware
 versions and care must be taken to select the appropriate module inside this
 package for your firmware printer:
-  - thermal_printer = The latest printers with firmware version 2.68+
-  - thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
-  - thermal_printer_legacy = Printers with firmware version before 2.64.
+
+* thermal_printer = The latest printers with firmware version 2.68+
+* thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
+* thermal_printer_legacy = Printers with firmware version before 2.64.
 
 * Author(s): Tony DiCola
 """
@@ -128,9 +129,13 @@ def feed(self, lines):
 
     def has_paper(self):
         """Return a boolean indicating if the printer has paper.  You MUST have
-        the serial RX line hooked up for this to work.  NOTE: be VERY CAREFUL
-        to ensure your board can handle a 5V serial input before hooking up
-        the RX line!
+        the serial RX line hooked up for this to work.
+
+        .. note::
+
+            be VERY CAREFUL to ensure your board can handle a 5V serial
+            input before hooking up the RX line!
+
         """
         # The paper check command is different for older firmware:
         self.send_command('\x1Br\x00')  # ESC + 'r' + 0

adafruit_thermal_printer/thermal_printer_legacy.py

@@ -0,0 +1,11 @@
+
+.. If you created a package, create one automodule per module in the package.
+
+.. automodule:: adafruit_thermal_printer.thermal_printer
+   :members:
+
+.. automodule:: adafruit_thermal_printer.thermal_printer_264
+   :members:
+
+.. automodule:: adafruit_thermal_printer.thermal_printer_legacy
+   :members:

api.rst

@@ -2,7 +2,7 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration ------------------------------------------------
 
@@ -18,7 +18,7 @@
 # Uncomment the below if you use native CircuitPython modules such as
 # digitalio, micropython and busio. List the modules you use. Without it, the
 # autodoc module docs will fail to generate with a warning.
-autodoc_mock_imports = ["micropython", "adafruit_thermal_printer"]
+autodoc_mock_imports = ["micropython"]#, "adafruit_thermal_printer"]
 
 intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
 
@@ -28,7 +28,7 @@
 source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'README'
+master_doc = 'index'
 
 # General information about the project.
 project = u'adafruit_thermal_printer Library'
@@ -54,7 +54,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -71,6 +71,9 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# If this is True, todo emits a warning for each TODO entries. The default is False.
+todo_emit_warnings = True
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -95,8 +98,14 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#
+html_favicon = '_static/favicon.ico'
+
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Adafruit_thermal_printerLibrarydoc'
+htmlhelp_basename = 'adafruit_thermal_printerLibrarydoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/_static/favicon.ico

@@ -0,0 +1,8 @@
+Simple test
+------------
+
+Ensure your device works with this simple test.
+
+.. literalinclude:: ../examples/thermal_printer_simpletest.py
+    :caption: examples/thermal_printer_simpletest.py
+    :linenos:

docs/api.rst

@@ -0,0 +1,47 @@
+.. include:: ../README.rst
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 4
+    :hidden:
+
+    self
+
+.. toctree::
+    :caption: Examples
+
+    examples
+
+.. toctree::
+    :caption: API Reference
+    :maxdepth: 3
+
+    api
+
+.. toctree::
+    :caption: Tutorials
+
+.. toctree::
+    :caption: Related Products
+
+    Mini Thermal Receipt Printer <https://www.adafruit.com/product/597>
+
+.. toctree::
+    :caption: Other Links
+
+    Download <https://github.com/adafruit/Adafruit_CircuitPython_Thermal_Printer/releases/latest>
+    CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
+    CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
+    Discord Chat <https://adafru.it/discord>
+    Adafruit Learning System <https://learn.adafruit.com>
+    Adafruit Blog <https://blog.adafruit.com>
+    Adafruit Store <https://www.adafruit.com>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`