diff --git a/readthedocs.yml b/.readthedocs.yml similarity index 100% rename from readthedocs.yml rename to .readthedocs.yml diff --git a/.travis.yml b/.travis.yml index 8d00bcf..1254b9a 100644 --- a/.travis.yml +++ b/.travis.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 diff --git a/README.rst b/README.rst index 4c066fb..4910c44 100644 --- a/README.rst +++ b/README.rst @@ -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. diff --git a/adafruit_thermal_printer/thermal_printer.py b/adafruit_thermal_printer/thermal_printer.py index 370f098..5e0f94c 100644 --- a/adafruit_thermal_printer/thermal_printer.py +++ b/adafruit_thermal_printer/thermal_printer.py @@ -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 + `_ (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. """ diff --git a/adafruit_thermal_printer/thermal_printer_264.py b/adafruit_thermal_printer/thermal_printer_264.py index 5151900..ed58920 100644 --- a/adafruit_thermal_printer/thermal_printer_264.py +++ b/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_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 """ diff --git a/adafruit_thermal_printer/thermal_printer_legacy.py b/adafruit_thermal_printer/thermal_printer_legacy.py index b3a0abe..94fed16 100644 --- a/adafruit_thermal_printer/thermal_printer_legacy.py +++ b/adafruit_thermal_printer/thermal_printer_legacy.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 diff --git a/api.rst b/api.rst deleted file mode 100644 index 1200bf7..0000000 --- a/api.rst +++ /dev/null @@ -1,5 +0,0 @@ - -.. If you created a package, create one automodule per module in the package. - -.. automodule:: adafruit_thermal_printer - :members: diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 0000000..5aca983 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..fbaa471 --- /dev/null +++ b/docs/api.rst @@ -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: \ No newline at end of file diff --git a/conf.py b/docs/conf.py similarity index 88% rename from conf.py rename to docs/conf.py index f89d9bf..803ba9e 100644 --- a/conf.py +++ b/docs/conf.py @@ -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 --------------------------------------------- diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..cbdbe8c --- /dev/null +++ b/docs/examples.rst @@ -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: diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..d9c56c6 --- /dev/null +++ b/docs/index.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 + +.. toctree:: + :caption: Other Links + + Download + CircuitPython Reference Documentation + CircuitPython Support Forum + Discord Chat + Adafruit Learning System + Adafruit Blog + Adafruit Store + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/examples/simpletest.py b/examples/thermal_printer_simpletest.py similarity index 100% rename from examples/simpletest.py rename to examples/thermal_printer_simpletest.py