Documentation Basics

README.md

@@ -2,4 +2,29 @@
 
 ![pydeohub](https://user-images.githubusercontent.com/37907774/195731748-53e8b78e-fc42-4e33-93c9-64b7ffa5bb33.png)
 
-Python interface for Blackmagic Design Smart Videohub SDI routers.
+Python interface for ethernet-connected Blackmagic Design Smart Videohub SDI routers.
+
+## Installation
+```
+pip install pydeohub
+```
+
+## Documentation
+A full API reference and small walkthrough is available on [Read the Docs](http://pydeohub.readthedocs.io/).
+
+## Example
+```python
+from pydeohub import Videohub
+
+hub = Videohub('192.168.0.150')
+
+hub.route(0, 0) # Note that input/output identifiers are 0-indexed.
+
+hub.input_label(1, 'Camera 2')
+hub.output_label(0, 'Switcher 1')
+```
+
+## Additional Information
+This is a work in progress and while it implements the vast majority of the Videohub Ethernet Protocol, it does not do everything.  The infrastructure around locking inputs and oututs, video processors, and serial controllers is unimplemented.
+
+Questions, comments, and contributions are welcome.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+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)

docs/api.rst

@@ -0,0 +1,7 @@
+API Reference
+=====================================
+
+Videohub
+---------
+.. automodule:: pydeohub
+    :members:

docs/conf.py

@@ -0,0 +1,46 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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('..'))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'pydeohub'
+copyright = '2022, Daniel Flanagan'
+author = 'Daniel Flanagan'
+release = '0.0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'numpydoc'
+]
+
+autodoc_member_order = 'bysource'
+numpydoc_show_class_members = False
+numpydoc_class_members_toctree = False
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,24 @@
+.. pydeohub documentation master file, created by
+   sphinx-quickstart on Wed Oct 19 15:49:05 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Pydeohub
+====================================
+Python interface for Blackmagic Design Smart Videohub SDI routers.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   intro
+   api
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/intro.rst

@@ -0,0 +1,52 @@
+Introduction
+============
+
+Installation
+------------
+
+This package is available on  ``pip``::
+
+    pip install pydeohub
+
+Requirements
+------------
+Pydeohub was developed with Python 3.9 but contains no external dependencies so should be compatiable with all current versions of Python 3.7+.
+
+The Smart Videohub you're using should be fully updated, this library was developed on a `Smart Videohub 20x20 <https://www.blackmagicdesign.com/products/smartvideohub/techspecs/W-VHS-02>`_ but should be compatiable with all recent Smart Videohub models with an ethernet connection.
+
+Getting Started
+----------------
+The following code example shows how to initiate a connection with a Videohub::
+    
+    from pydeohub import Videohub
+
+    hub = Videohub('192.168.0.150')
+
+=================
+Routing
+=================
+There are two way to re-route inputs and outputs on the Smart Videohub, individual changes or bulk changes::
+
+    hub.route(0, 0) # Routes Input 1 to Output 1
+
+    bulk_routes = [
+        (0, 0),
+        (1, 1),
+        (2, 2),
+        (3, 3),
+        (4, 4),
+        (5, 5)
+    ]
+    hub.bulk_route(bulk_routes) # Routes Inputs 1-6 to Outputs 1-6
+
+.. note:: All input and output identifiers are 0-indexed so 'Input 1' is actually identifier `0`.
+
+=================
+Labels
+=================
+Each input and output has an associated label that is displayed on the Videohub's built-in display and most accompying Blackmagic software integrations.  Pydeohub can modify these labels programatically::
+
+    hub.input_label(0, 'Camera 1') # Label Input 1 as Camera 1
+
+    hub.output_label(19, 'Main TV') # Label Output 20 as Main TV
+

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

pydeohub/__init__.py

@@ -154,7 +154,7 @@ def bulk_route(self, routes: List[Tuple[int, int]]) -> None:
         Parameters
         ----------
         routes : List[Tuple[int, int]]
-            A list of (destination, source) vido output/input identifiers.
+            A list of (destination, source) video output/input identifiers.
         """
         command = ''
         for route in routes:

requirements-dev.txt

@@ -9,6 +9,7 @@ imagesize==1.4.1
 importlib-metadata==5.0.0
 Jinja2==3.1.2
 MarkupSafe==2.1.1
+numpydoc==1.5.0
 packaging==21.3
 Pygments==2.13.0
 pyparsing==3.0.9