Add Sphinx metadata so documentation can be generated. Document the d…

…ocbuild in the readme. Put newlines between newlines as per reStructuredText so they show up as bullets in the documentation.

.gitignore

@@ -13,4 +13,6 @@
 /*.bad_json.txt
 /settings.json
 /.vscode/settings.json
-# ^ /.vscode/settings.json is ignored since it may have python.defaultInterpreterPath with differs depending on the specific machine. Recommended: place that setting in there ("PythonOlcbNode Folder" tab in VSCode settings)
+# ^ /.vscode/settings.json is ignored since it may have python.defaultInterpreterPath with differs depending on the specific machine. Recommended: place that setting in there ("PythonOlcbNode Folder" tab in VSCode settings)
+/build
+/doc/_autosummary

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     = doc
+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)

README.md

@@ -23,7 +23,7 @@ Linux:
 mkdir -p ~/.virtualenvs
 python3 -m venv ~/.virtualenvs/pytest-env
 source ~/.virtualenvs/pytest-env/bin/activate
-``` 
+```
 
 Windows:
 ```
@@ -51,11 +51,21 @@ If using VSCode (or fully open-source VSCodium):
   - (recommended) **autoDocstring**: Type `"""` below a method or class and it will create a Sphinx-style template for you.
     - The workspace file has `"autoDocstring.docstringFormat": "google"` set since Google style is widely used and comprehensive (documents types etc).
 
+#### Documentation
+The sources for building documentation are:
+- rst (reStructuredText) file(s) in the doc directory
+- Google-style docstrings which is one of the formats recognized by Sphinx (and one with a thorough explanation of input and output types).
+
+To generate documentation that can be placed on a website (such as could be published to readthedocs.io automatically) or provided to end users, run:
+```
+make html
+```
+
 ### Testing
 To run the unit test suite:
 ```
 python3 -m pip install --user pytest
-# ^ or use a 
+# ^ or use a
 python3 -m pytest
 # or to auto-detect test and run with standard log level:
 # python3 -m pytest tests
@@ -84,7 +94,7 @@ python3 example_node_implementation.py 192.168.1.40
 python3 example_node_implementation.py 192.168.1.40:12021
 ```
 
-There's also a serial-port based example. 
+There's also a serial-port based example.
 ```
 python3 example_string_serial_interface.py /dev/cu.ProperSerialPort
 ```

doc/_templates/custom-class-template.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

doc/conf.py

@@ -0,0 +1,38 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+project = 'python-openlcb'
+copyright = '2024, Bob Jacobsen'
+author = 'Bob Jacobsen'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.coverage',
+    'sphinx.ext.napoleon',  # understands NumPy and Google docstrings.
+]
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

doc/index.rst

@@ -0,0 +1,49 @@
+.. python-openlcb documentation master file, created by
+   sphinx-quickstart on Thu May 16 16:30:21 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to python-openlcb's documentation!
+==========================================
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   openlcb
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. image:: Overview.png
+  :width: 400
+  :alt: Flowchart of the software-defined node's network connection
+
+For how this documentation is built into html, see README.md or create a github workflow to publish it to readthedocs.io.
+
+For general info on how the "docbuild" was configured, see the following sources which where used:
+
+- Install Sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html
+
+- Setup autodoc: https://eikonomega.medium.com/getting-started-with-sphinx-autodoc-part-1-2cebbbca5365
+
+- Setup recursive gathering of docstrings using autosummary: https://stackoverflow.com/a/62613202/4541104
+
+Instructions for adding new documentation:
+
+- Use Google-style docstrings (Sphinx will automatically generate documentation sections for such docstrings when `make html` runs).
+
+- For bullet lists within docstrings, reStructuredText must be used (blank line before each bullet).
+
+- For additional text that is manually entered (not generated from docstrings),
+  use the reStructuredText format and add data to this file or other rst files
+  (in the "doc" folder in the case of this project, as configured in make.bat
+  and Makefile).
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

examples_gui.py

@@ -73,8 +73,10 @@ class MainForm(ttk.Frame):
 
     The program is organized into fields. Each field contains a label, entry
     widget, and potentially a tooltip Label and command button.
+
     - The entry widget for each field may be a ttk.Entry, ttk.Combobox, or
       potentially another ttk widget subclass.
+
     - Each field has a key. Only keys in self.settings are directly used
       as settings.
 

make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=doc
+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

openlcb/canbus/canlink.py

@@ -10,10 +10,12 @@
 
 This implementation handles one static Local Node and a variable number of
 Remote Nodes.
- - An alias is allocated for the Local Node when the link comes up.
- - Aliases are tracked for the Remote Nodes, but not allocated here
 
- Multi-frame addressed messages are accumulated in parallel
+- An alias is allocated for the Local Node when the link comes up.
+
+- Aliases are tracked for the Remote Nodes, but not allocated here
+
+Multi-frame addressed messages are accumulated in parallel
 '''
 
 from enum import Enum
@@ -623,8 +625,11 @@ def canHeaderToFullFormat(self, frame):
 
     class AccumKey:
         '''Class that holds the ID for accumulating a multi-part message:
+
         - MTI
+
         - Source
+
         - Destination
 
         Together these uniquely identify a stream of frames that need to

openlcb/canbus/seriallink.py

@@ -1,5 +1,5 @@
 '''
-simple serial nput for string send and receive
+simple serial input for string send and receive
 expects prior setting of device name
 '''
 import serial
@@ -8,6 +8,7 @@
 
 
 class SerialLink:
+    """simple serial input for string send and receive"""
     def __init__(self):
         pass
 
@@ -42,9 +43,12 @@ def send(self, string):
 
     def receive(self):
         '''Receive at least one GridConnect frame and return as string.
-        - Guarantee: If input is valid, there will be at least one ";" in the
-          response.
+
+        - Guarantee: If input is valid, there will be at least one ";"
+          in the response.
+
         - This makes it nicer to display the raw data.
+
         - Note that the response may end with a partial frame.
 
         Returns:

openlcb/canbus/tcpsocket.py

@@ -39,9 +39,12 @@ def send(self, string):
 
     def receive(self):
         '''Receive at least one GridConnect frame and return as string.
+
         - Guarantee: If input is valid, there will be at least one ";" in the
           response.
+
         - This makes it nicer to display the raw data.
+
         - Note that the response may end with a partial frame.
 
         Returns:

openlcb/memoryservice.py

@@ -109,8 +109,10 @@ def spaceDecode(self, space):
 
     def requestMemoryRead(self, memo):
         '''Request a read operation start.
+
         - If okReply in the memo is triggered, it will be followed by a
           dataReply.
+
         - A rejectedReply will not be followed by a dataReply.
 
         Args:

openlcb/remotenodestore.py

@@ -48,6 +48,7 @@ def createNewRemoteNode(self, message) :
         A new node was found by checkForNewNode, so this
         mutates the store to add this.  This should only be called
         if checkForNewNode is true to avoid excess publishing!
+
         - Parameter message: Incoming message to process
         '''
         # need to create the node and process it's New_Node_Seen