initial setup of GitHub Docs

docs/_static/css/sphinx_design_overrides.css

@@ -0,0 +1,9 @@
+/* Override for the sphinx-design extension classes */
+.sd-card-header {	
+  font-size: 110% !important;
+  font-family: Audiowide,Helvetica,Arial,sans-serif !important;
+  font-weight: 500 !important;  
+  color: #00a3b9ff;
+  text-shadow: 1px 1px 0 #00353dff;
+  margin-bottom: .5rem !important;
+}

docs/conf.py

@@ -0,0 +1,95 @@
+# 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
+
+# from sphinx.builders.html import StandaloneHTMLBuilder
+import subprocess
+# import os
+
+# Doxygen
+subprocess.call('doxygen Doxyfile.in', shell=True)
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'DCCEXProtocol'
+copyright = '2023 - Peter Cole, Peter Akers'
+author = 'Peter Cole, Peter Akers'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+  'sphinx_sitemap',
+  'sphinxcontrib.spelling',
+  'sphinx_rtd_dark_mode',
+  'breathe'
+]
+
+autosectionlabel_prefix_document = True
+
+# Don't make dark mode the user default
+default_dark_mode = False
+
+spelling_lang = 'en_UK'
+tokenizer_lang = 'en_UK'
+spelling_word_list_filename = ['spelling_wordlist.txt']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+highlight_language = 'c++'
+
+numfig = True
+
+numfig_format = {'figure': 'Figure %s'}
+
+# -- 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']
+
+html_logo = "./_static/images/product-logo-native-protocol-library.png"
+
+html_favicon = "./_static/images/favicon.ico"
+
+html_theme_options = {
+    'style_nav_header_background': 'white',
+    'logo_only': True,
+    # Toc options
+    'includehidden': True,
+    'titles_only': False,
+    # 'titles_only': True,
+    'collapse_navigation': False,
+    # 'navigation_depth': 3,
+    'navigation_depth': -1,
+    'analytics_id': 'G-L5X0KNBF0W',
+}
+
+html_context = {
+    'display_github': True,
+    'github_user': 'DCC-EX',
+    'github_repo': 'dccexprotocol',
+    'github_version': 'sphinx/docs/',
+}
+
+html_css_files = [
+    'css/dccex_theme.css',
+    'css/sphinx_design_overrides.css',
+]
+
+# Sphinx sitemap
+html_baseurl = 'https://dcc-ex.com/DCCEXProtocol/'
+html_extra_path = [
+  'robots.txt',
+]
+
+# -- Breathe configuration -------------------------------------------------
+
+breathe_projects = {
+  "DCCEXProtocol": "_build/xml/"
+}
+breathe_default_project = "DCCEXProtocol"
+breathe_default_members = ()

docs/include/include.rst

@@ -0,0 +1,53 @@
+.. meta::
+  :keywords: DCC-EX DCC DCC++ EX DCC++EX 
+..
+.. |DCC-EX| raw:: html
+
+  <a href="https://dcc-ex.com/"><span class="dccex-suffix">DCC-</span><span class="dccex-prefix">EX</span></a>
+..
+.. |EX-CS| raw:: html
+
+  <a href="https://dcc-ex.com/"><span class="ex-prefix">EX</span><span class="ex-suffix">&#8209;CommandStation</span></a>
+..
+.. |EX-NCL| raw:: html
+
+  <span class="dccex-suffix">DCC-</span><span class="dccex-prefix">EX</span>
+  <span class="ex-suffix">Native command protocol library</span>
+..
+.. |EX-P| raw:: html
+
+  <span class="ex-prefix">DCCEX</span><span class="ex-suffix">Protocol</span>
+..
+.. |EX-PL| raw:: html
+
+  <span class="ex-prefix">DCCEX</span><span class="ex-suffix">Protocol library</span>
+..
+.. |EX-NCP| raw:: html
+
+  <span class="dccex-suffix">DCC-</span><span class="dccex-prefix">EX</span>
+  <span class="ex-suffix"> native command protocol</span>
+..
+.. |br| raw:: html
+
+  <br />
+..
+.. role:: dcc-ex-red
+.. role:: dcc-ex-red-bold
+.. role:: dcc-ex-red-bold-italic
+.. role:: dcc-ex-code
+..
+.. role:: dcc-ex-text-size-80pct
+.. role:: dcc-ex-text-size-60pct
+.. role:: dcc-ex-text-size-200pct
+..
+.. |_| unicode:: 0xA0
+  :trim:
+..
+.. |force-break| raw:: html
+
+  <div style="display:block; box-sizing: border-box; clear: both;"> </div>
+..
+.. |image-note| raw:: html
+
+  <span style="font-weight: bold; font-style: italic; color: #767676;" >Note that you can click on any of the images to make them larger.</span>
+..

docs/index.rst

@@ -0,0 +1,47 @@
+.. include:: /include/include.rst
+
+Documentation for the WiThrotle protocol library - WiThrottleProtocol
+=====================================================================
+
+.. toctree::
+  :maxdepth: 4
+  :hidden:
+
+  WiThrottle protocol library <self>
+  library
+
+WiThrottle protocol library
+---------------------------
+
+This library implements the WiThrottleProtocol (as used in JMRI, the |DCC-EX| |EX-CS| and manya other DCc Command Stations), allowing a device to connect to the server and act as a client (such as a hardware based throttle).
+
+The implementation of this library is tested on ESP32 based devices running the Arduino framework. There's nothing in here that's specific to the ESP32, and little of Arduino that couldn't be replaced as needed.
+
+Credits
+-------
+
+The original version of the code in this library is taken directly from the WiThrottle library by **Copyright © 2018-2019 Blue Knobby Systems Inc.** and additioanl changes by lucadentella.
+The rest of the code has been developed by Peter Akers (Flash62au).
+
+-----
+
+Differences from the original library
+=====================================
+
+ - Removed dependencies with external libraries (Chrono.h, ArduinoTime.h, TimeLib.h) 
+ - Added NullStream class to disable (by default) logging
+ - Changed begin() method to setLogStream()
+ - Added a setter method for delegate class: setDelegate()
+ - Added the ability to parse roster messages and to receive the roster list via delegate class
+
+Differences from the lucadentella version of the library
+========================================================
+
+ - Added the trademark changes from the original library
+ - supports multi-throttle commands (max 6)  (Added in version 1.1.0)
+ - Support added for on-the-fly consists
+ - Support added for turnouts/points
+ - Support added for routes
+ - Heartbeat sends the device name, which forces the WiThrottle server to respond (used to confirm it is still connected)
+ - minimum time separation/delay between commands sent (introduced in v1.1.7)
+ - bug fixes

docs/library.rst

@@ -0,0 +1,5 @@
+Library
+=======
+
+.. doxygenindex:: 
+  :project: WiThrottleProtocol

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

docs/make2 github.bat

@@ -0,0 +1,4 @@
+"C:\Program Files\doxygen\bin\doxygen" Doxyfile.in
+
+call make2 github
+pause

docs/make2.bat

@@ -0,0 +1,52 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+@REM set SPHINXOPTS=-E -a
+
+if "%1" == "" goto help
+
+if "%1" == "github" (
+    %SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+	echo "dcc-ex.com" /y > docs\_build\html\CNAME
+	echo "" /y > docs\_build\html\.nojekyll
+    goto end
+)
+
+@REM if "%1" == "clean" (
+@REM 		rmdir /S /Q %BUILDDIR%
+@REM 		mkdir %BUILDDIR%
+@REM 		@REM %SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+@REM 	@REM echo "dcc-ex.com" /y > docs\_build\html\CNAME
+@REM 	@REM echo "" /y > docs\_build\html\.nojekyll
+@REM     goto end
+@REM )
+
+%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.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+

library.properties

@@ -3,7 +3,7 @@ version=1.1.17
 author=Peter Akers <akersp62@gmail.com>, David Zuhn <zoo@statebeltrailway.org>, Luca Dentella <luca@dentella.it>
 maintainer=Peter Akers <akersp62@gmail.com>
 sentence=JMRI WiThrottle Protocol implementation for ESP32
-paragraph=This library implements the WiThrottle protocol (as used in JMRI and other servers), allowing an device to connect to the server and act as a client (such as a dedicated fast clock device or a hardware based throttle).
+paragraph=This library implements the WiThrottle protocol (as used in JMRI and other servers), allowing an Ardunio device to connect to the server and act as a client (such as a dedicated fast clock device or a hardware based throttle).
 category=Other
 url=https://github.com/flash62au/WiThrottleProtocol
 architectures=*

src/WiThrottleProtocol.h

@@ -110,10 +110,12 @@ class NullStream : public Stream {
 	size_t write(const uint8_t *buffer, size_t size) { return size; }
 };
 
+/// @brief Class for the 
 class WiThrottleProtocolDelegate
 {
   public:
-
+    /// @brief Constructor
+    /// @param id Route ID
     virtual void receivedVersion(String version) {}
     virtual void receivedServerType(String type) {}
     virtual void receivedServerDescription(String description) {}