Sphinx Docs

sphinx/_static/custom.css

@@ -0,0 +1,41 @@
+.rst-content a, .rst-content a:focus {
+    color:#13c0d7;
+}
+.rst-content a:visited, .rst-content a:active {
+    color:#87319a;
+}
+.rst-content .highlighted {
+	background:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAJElEQVQIW2P8//9/PSMjYyMDEmAEsdElwILoEnBBZAkUQZgEABMWE4Kzp1KUAAAAAElFTkSuQmCC),rgba(246,167,4,0.2);
+	margin:0 -6px;
+}
+.wy-side-nav-search {
+    background:#333333;
+}
+.wy-nav-side {
+    background:#444444;
+}
+.rst-content dl:not(.docutils) dt {
+    background:#e7fafd;
+    border-top:solid 3px #13c0d7;
+    color:rgba(0,0,0,0.5);
+}
+.rst-content .viewcode-link, .rst-content .viewcode-back {
+    color:#00b09b;
+}
+code.literal {
+    color:#e63c2e;
+}
+.rst-content #at-a-glance {
+    margin-bottom:24px;
+}
+.rst-content #at-a-glance dt,
+.rst-content #at-a-glance dd dl:not(.docutils) dt {
+    border:none;
+    background:#f0f0f0;
+}
+.rst-content #at-a-glance dd dl:not(.docutils) dd {
+    display:none;
+}
+.rst-content #at-a-glance dd dl:not(.docutils) {
+    margin-bottom:0;
+}

sphinx/_templates/layout.html

@@ -0,0 +1,43 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+	<link rel="stylesheet" href="{{ pathto("_static/custom.css", True) }}" type="text/css">
+{% endblock %}
+{% block footer %}
+<script type="text/javascript">
+	var menuItems = $('.wy-menu-vertical').find('a');
+
+	var scrollItems = menuItems.map(function(){
+		var item = $($(this).attr('href'));
+		if (item.length) { return item; }
+	});
+
+	$(window).on('scroll',function(){
+		var fromTop = $(this).scrollTop()
+
+		var cur = scrollItems.map(function(){
+			if ($(this).offset().top < fromTop+30) return this;
+		});
+
+		cur = cur[cur.length-1];
+		var id = cur && cur.length ? cur[0].id : "";
+
+		var target = $('#'+id);
+		target.attr('id','');
+		window.location.hash = '#'+id;
+		target.attr('id',id);
+
+		menuItems
+			.parent().removeClass("current")
+			.end().filter("[href='#"+id+"']").parent().addClass("current");
+	});
+
+	$(window).on('hashchange',function(){
+
+		var hash = window.location.hash.replace('#','');
+
+		menuItems
+			.parent().removeClass("current")
+			.end().filter("[href='#"+hash+"']").parent().addClass("current");
+	})
+</script>
+{% endblock %}

sphinx/conf.py

@@ -5,11 +5,6 @@
 
 import mock
 
-
-PACKAGE_NAME = u"PanTiltHAT"
-PACKAGE_HANDLE = "PanTiltHAT"
-PACKAGE_MODULE = "pantilthat"
-
 # Prompte /usr/local/lib to the front of sys.path
 #sys.path.insert(0,site.getsitepackages()[0])
 
@@ -19,6 +14,57 @@
 
 sys.path.insert(0, '../library/')
 
+
+from sphinx.ext import autodoc
+
+
+class OutlineMethodDocumenter(autodoc.MethodDocumenter):
+    objtype = 'method'
+
+    def add_content(self, more_content, no_docstring=False):
+        return
+
+class OutlineFunctionDocumenter(autodoc.FunctionDocumenter):
+    objtype = 'function'
+
+    def add_content(self, more_content, no_docstring=False):
+        return
+
+class ClassOutlineDocumenter(autodoc.ClassDocumenter):
+    objtype = 'classoutline'
+
+    def add_content(self, more_content, no_docstring=False):
+        return
+
+    def __init__(self, directive, name, indent=u''):
+        # Monkey path the Method and Function documenters
+        sphinx_app.add_autodocumenter(OutlineMethodDocumenter)
+        sphinx_app.add_autodocumenter(OutlineFunctionDocumenter)
+        autodoc.ClassDocumenter.__init__(self, directive, name, indent)
+
+    def __del__(self):
+        # Return the Method and Function documenters to normal
+        sphinx_app.add_autodocumenter(autodoc.MethodDocumenter)
+        sphinx_app.add_autodocumenter(autodoc.FunctionDocumenter)
+
+
+def setup(app):
+    global sphinx_app
+    sphinx_app = app
+    app.add_autodocumenter(ClassOutlineDocumenter)
+
+    ClassOutlineDocumenter.objtype = 'class'
+
+
+import pantilthat
+
+PACKAGE_NAME = u"PanTiltHAT"
+PACKAGE_HANDLE = "PanTiltHAT"
+PACKAGE_MODULE = "pantilthat"
+PACKAGE_VERSION = pantilthat.__version__
+
+suppress_warnings = ["app.add_directive"]
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -30,6 +76,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.viewcode',
 ]
 
@@ -51,17 +98,17 @@
 
 # General information about the project.
 project = PACKAGE_NAME
-copyright = u'2016, Phil Howard'
+copyright = u'2016, Pimoroni Ltd'
 author = u'Phil Howard'
 
 # 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 = u'0.0.1'
+version = u'{}'.format(PACKAGE_VERSION)
 # The full version, including alpha/beta/rc tags.
-release = u'0.0.1'
+release = u'{}'.format(PACKAGE_VERSION)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -128,7 +175,10 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'collapse_navigation': False,
+    'display_version': True
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = [
@@ -148,13 +198,13 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-# html_logo = None
+html_logo = 'shop-logo.png'
 
 # 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 = None
+html_favicon = 'favicon.png'
 
 # 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,
@@ -193,19 +243,19 @@
 
 # If false, no index is generated.
 #
-# html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #
 # html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
 #
-# html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #
-# html_show_sphinx = True
+html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 #

sphinx/index.rst

@@ -1,25 +1,90 @@
-============
-PanTilt HAT!
-============
+.. role:: python(code)
+   :language: python
 
-Welcome to the PanTilt HAT documentation.
+Welcome
+-------
 
-Function Reference
-==================
+This documentation will guide you through the methods available in the Pan Tilt HAT python library.
 
-.. autoclass:: pantilthat.PanTilt
+Pan-Tilt HAT lets you mount and control one of our pan-tilt modules right on top of your Raspberry Pi. The HAT and its on-board microcontroller let you independently drive the two servos (pan and tilt), as well as driving up to 24 regular LED (with PWM control) or NeoPixel RGB (or RGBW) LEDs
+
+* More information - https://shop.pimoroni.com/products/pan-tilt-hat
+* Get the code - https://github.com/pimoroni/pantilt-hat
+* Get help - http://forums.pimoroni.com/c/support
+
+At A Glance
+-----------
+
+.. autoclassoutline:: pantilthat.PanTilt
    :members:
 
-Constants
+Set Brightness
+--------------
+
+.. automethod:: pantilthat.pantilthat.brightness
+
+Clear
+-----
+
+.. automethod:: pantilthat.pantilthat.clear
+
+Set Light Mode
+--------------
+
+.. automethod:: pantilthat.pantilthat.light_mode
+
+Pan
+---
+
+.. automethod:: pantilthat.pantilthat.pan
+
+.. automethod:: pantilthat.pantilthat.servo_one
+
+Tilt
+----
+
+.. automethod:: pantilthat.pantilthat.tilt
+
+.. automethod:: pantilthat.pantilthat.servo_two
+
+Servo Enable
+------------
+
+.. automethod:: pantilthat.pantilthat.servo_enable
+
+Servo Pulse Min
+---------------
+
+.. automethod:: pantilthat.pantilthat.servo_pulse_min
+
+Servo Pulse Max
+---------------
+
+.. automethod:: pantilthat.pantilthat.servo_pulse_max
+
+Set All LEDs
+------------
+
+.. automethod:: pantilthat.pantilthat.set_all
+
+Set A LED
 ---------
 
-WS2812 = 1
-PWM = 0
+.. automethod:: pantilthat.pantilthat.set_pixel
+
+Set A LED (RGBW)
+----------------
+
+.. automethod:: pantilthat.pantilthat.set_pixel_rgbw
 
+Show
+----
 
-Indices and tables
-==================
+.. automethod:: pantilthat.pantilthat.show
+
+Constants
+---------
 
-* :ref:`genindex`
-* :ref:`search`
+* :python:`WS2812 = 1` - used with :python:`pantilthat.light_mode` to set WS2812 LEDs
+* :python:`PWM = 0` - used with :python:`pantilthat.light_mode` to set PWM dimmed LEDs