From fcb74a0690baaf9dfa4d1f3f8a1766c44a5104ee Mon Sep 17 00:00:00 2001 From: Felipe Martin Date: Mon, 30 Jan 2017 14:07:51 +0100 Subject: [PATCH] Initial documentation attempt --- docs/Makefile | 20 +++++ docs/source/conf.py | 157 ++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 23 ++++++ docs/source/luxafor.rst | 22 ++++++ docs/source/modules.rst | 7 ++ docs/source/specs.rst | 4 + luxafor/luxafor.py | 63 +++++++++++----- requirements.txt | 0 8 files changed, 278 insertions(+), 18 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/luxafor.rst create mode 100644 docs/source/modules.rst create mode 100644 docs/source/specs.rst create mode 100644 requirements.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..6508928 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = pyluxafor +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..fa80c85 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,157 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# pyluxafor documentation build configuration file, created by +# sphinx-quickstart on Fri Jan 27 13:53:00 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../../')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'pyluxafor' +copyright = '2017, Felipe Martin' +author = 'Felipe Martin' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = 'alpha' +# The full version, including alpha/beta/rc tags. +release = 'alpha' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# 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 = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'pyluxafordoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'pyluxafor.tex', 'pyluxafor Documentation', + 'Felipe Martin', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pyluxafor', 'pyluxafor Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'pyluxafor', 'pyluxafor Documentation', + author, 'pyluxafor', 'One line description of project.', + 'Miscellaneous'), +] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..185eb38 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,23 @@ +.. pyluxafor documentation master file, created by + sphinx-quickstart on Fri Jan 27 13:53:00 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to pyluxafor's documentation! +===================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + specs + +.. automodule:: + fluxafor.luxafor + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/luxafor.rst b/docs/source/luxafor.rst new file mode 100644 index 0000000..b77c8db --- /dev/null +++ b/docs/source/luxafor.rst @@ -0,0 +1,22 @@ +luxafor package +=============== + +Submodules +---------- + +luxafor.luxafor module +---------------------- + +.. automodule:: luxafor.luxafor + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: luxafor + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..9593cd6 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +luxafor +======= + +.. toctree:: + :maxdepth: 4 + + luxafor diff --git a/docs/source/specs.rst b/docs/source/specs.rst new file mode 100644 index 0000000..e9fbabc --- /dev/null +++ b/docs/source/specs.rst @@ -0,0 +1,4 @@ +Luxafor specification +===================== + +asdlj diff --git a/luxafor/luxafor.py b/luxafor/luxafor.py index 40498fd..fff97a7 100644 --- a/luxafor/luxafor.py +++ b/luxafor/luxafor.py @@ -8,25 +8,28 @@ class Leds(object): """ Helper class with static attributes to select Luxafor leds. - - All: All the leds. - - Front: Front side of the flag. - - Back: Back side of the flag. - - Led#: Specific led number. + - **All**: All the leds. + - **Front**: Front side of the flag. + - **Back**: Back side of the flag. + - **Led#**: Specific led number. - +--------------------------+ - | | | - |6 3| | - | | | - Front side|5 2|Back side | - | | | - |4 1| | - | | | - | +---------------------+ - | | - | | - | | - | | - +----+ + + :: + + +--------------------------+ + | | | + |6 3| | + | | | + Front side|5 2|Back side | + | | | + |4 1| | + | | | + | +---------------------+ + | | + | | + | | + | | + +----+ """ ALL = 0xFF BACK = 0x41 @@ -41,6 +44,11 @@ class Leds(object): class Packet(object): + """ + Helper class to make it easy send the bytecode into the + luxafor flag via USB. + """ + byte0 = 0 byte1 = 0 byte2 = None @@ -51,9 +59,11 @@ class Packet(object): byte7 = None def get_byte(self, byte_num): + """Returns the requested byte number""" return getattr(self, 'byte%d' % byte_num, None) def render(self): + """Returns the ordered byte-list to send via USB.""" pkt = filter( lambda x: x is not None, (self.get_byte(n) for n in range(8))) @@ -61,6 +71,9 @@ class Packet(object): class Luxafor(object): + """ + Main object to interact with luxafor flags. + """ VENDOR_ID = 0x04D8 PRODUCT_ID = 0xF372 @@ -78,6 +91,9 @@ class Luxafor(object): } def __init__(self): + """ + Finds the device to allow sending it information to. + """ device = usb.core.find(idVendor=self.VENDOR_ID, idProduct=self.PRODUCT_ID) @@ -94,6 +110,12 @@ class Luxafor(object): self.device = device def set_basic_color(self, color): + """ + Set's up a basic color defined by the luxafor spec. + + Possible values are set in the :attr:`~luxafor.Luxafor.COLORS`: + attribute in this class. + """ if color in self.COLORS: pkt = Packet() pkt.byte0 = 0 @@ -102,6 +124,11 @@ class Luxafor(object): self.device.write(self.DEVICE_ID, pkt.render()) def set_color(self, red=255, green=255, blue=255, led=Leds.ALL): + """ + Sets a fixed color defined by the user. + + Using the `led` attribute. + """ pkt = Packet() pkt.byte0 = 1 pkt.byte1 = led diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..e69de29