Initial conversion to MyST

docs/conf.py

@@ -14,14 +14,6 @@
 import sys
 #sys.path.insert(0, os.path.abspath('.'))
 import subprocess
-import recommonmark
-
-# for MarkdownParser
-from recommonmark.transform import AutoStructify
-from sphinx_markdown_parser.parser import MarkdownParser
-
-# At top on conf.py (with other import statements)
-from sphinx_markdown_parser.transform import AutoStructify
 
 import sphinx_bootstrap_theme
 from sphinx.ext import todo
@@ -49,7 +41,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['recommonmark', 'sphinx.ext.todo']
+extensions = ['myst_parser', 'sphinx.ext.todo']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -60,7 +52,7 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = '.md'
 
 # The master toctree document.
 master_doc = 'index'

docs/context/about/index.rst → docs/context/about/index.md

@@ -1,11 +1,11 @@
-.. _about:
+(about)=
 
-About Keg Cop
-###############
+# About Keg Cop
 
 The About page shows the currently installed version in the header.  Additionally, it contains links to the main website, the license under which I have released Keg Cop, and a link to my profile on Homebrewtalk.
 
-.. image:: about.png
-   :scale: 25%
-   :align: center
-   :alt: About Keg Cop
+```{image} about.png
+:align: center
+:alt: About Keg Cop
+:scale: 25%
+```

docs/context/about/license.md

@@ -0,0 +1,11 @@
+(license)=
+
+# Keg Cop License
+
+I have released Keg Cop under the [MIT License](https://github.com/lbussy/keg-cop/blob/master/LICENSE).
+
+```{image} license.png
+:align: center
+:alt: Keg Cop License
+:scale: 50%
+```

docs/context/help/index.md

@@ -0,0 +1,17 @@
+(help)=
+
+# Help Links
+
+The Help page displays important support links for Keg Cop:
+
+```{image} help.png
+:align: center
+:alt: Help Links
+:scale: 50%
+```
+
+- [Visit the Homepage](https://www.kegcop.com): A link to the Keg Cop main website.
+- [Visit project on GitHub](https://github.com/lbussys/keg-cop): A link to the GitHub repository.
+- [Read the Documentation](https://docs.kegcop.com): A link to this documentation.
+- [Report an issue or bug](https://github.com/lbussy/keg-cop/issues): A link to the Issues list within the GitHub repository. Use this for real issues or bugs; for support or questions, use the next link.
+- [Get support or chat with other users on the HomebrewTalk Thread](https://support.kegcop.com): A link to the main thread on HomebrewTalk where general discussions and "how do I?" conversations should be posted.

docs/context/home/index.rst → docs/context/home/index.md

@@ -1,18 +1,20 @@
-.. _home:
+(home)=
 
+```{eval-rst}
 .. include:: <xhtml1-symbol.txt>
+```
 
-Home Page
-##############
+# Home Page
 
-.. image:: home.png
-   :scale: 50%
-   :align: center
-   :alt: Home Page
+```{image} home.png
+:align: center
+:alt: Home Page
+:scale: 50%
+```
 
-The Keg Cop home page is displayed when you first connect via your chosen web browser.  You will see a main menu across the top border if you connect with a standard desktop web browser.  If in a mobile or portrait mode browser window, the list displays when you click the hamburger bar (|equiv|) in the top-right corner.
+The Keg Cop home page is displayed when you first connect via your chosen web browser.  You will see a main menu across the top border if you connect with a standard desktop web browser.  If in a mobile or portrait mode browser window, the list displays when you click the hamburger bar ({{ equiv }}) in the top-right corner.
 
-In the top-left side of the main container is a title concatenated from the :ref:`kegerator <controller>` and :ref:`brewery name <controller>` (e.g. "Main Kegerator in Silver Fox Brewery.")
+In the top-left side of the main container is a title concatenated from the {ref}`kegerator <controller>` and {ref}`brewery name <controller>` (e.g. "Main Kegerator in Silver Fox Brewery.")
 
 On the right side of this container is the current control point temperature if used.  The block around the temperature indicates the temperature control status. You may also hover over this section for a tooltip explaining the state.
 

docs/context/index.md

@@ -0,0 +1,29 @@
+(context)=
+
+# Context Help
+
+The following are links to context help for the web pages controlling the Keg Cop application.  Generally these are accessed via a hotlink in the web UI.
+
+```{toctree}
+:glob: true
+:maxdepth: 1
+:titlesonly: true
+
+home/index
+temperatures/index
+settings/controller/index
+settings/taps/index
+settings/temperature/control/index
+settings/temperature/sensors/index
+settings/targets/kegscreen/index
+settings/targets/url/index
+settings/targets/rpints/index
+settings/targets/taplistio/index
+settings/advanced/calibrate/index
+settings/advanced/reset/index
+settings/advanced/update/index
+settings/advanced/wifi/index
+help/index
+about/index
+about/license
+```

docs/context/settings/advanced/calibrate/index.rst → docs/context/settings/advanced/calibrate/index.md

@@ -1,38 +1,38 @@
-.. _calibrate:
+(calibrate)=
 
-Calibrate Flowmeters
-######################
+# Calibrate Flowmeters
 
-.. image:: calibrate.png
-   :scale: 50%
-   :align: center
-   :alt: Flowmeter Calibration Screen
+```{image} calibrate.png
+:align: center
+:alt: Flowmeter Calibration Screen
+:scale: 50%
+```
 
 Upon opening the Calibrate Flowmeters page, you are presented with a dropdown to select the flowmeter to be calibrated. After choosing the meter, select a radio button to select between calibrating by a weight or a volume measurement.  The Choose Mode button will activate upon selecting a method. Pressing this button will open an additional dialog, depending upon your choice.
 
 Calibration by volume is often less accurate than weight; however, using volume is the most straightforward method.
 
-Calibration by Volume
-**********************
+## Calibration by Volume
 
-.. image:: volume.png
-   :scale: 50%
-   :align: center
-   :alt: Calibration by Volume Screen
+```{image} volume.png
+:align: center
+:alt: Calibration by Volume Screen
+:scale: 50%
+```
 
 Calibration by volume involves measuring a tap pull of a beverage and then recording that measurement. A larger pour will be more accurate than a smaller one. Enter volume measurements in the units for which you have configured Keg Cop. Use milliliters if using metric, or ounces if using imperial measurements.
 
 As you draw a beverage during calibration, the Pulses field will update with the pulses measured. If you have entered a volume, the pulses per unit (PPG or PPL) are calculated. Both the Pulses and pulses per unit will update every two seconds.
 
 When you are satisfied, use the Set PPG/PPL button to lock in the calibration. If you wish to reset the calculation back to its default, use the Reset button instead of saving. The pulses collected will be debited according to the new rate if you save, or the previously configured rate if you reset.
 
-Calibration by Weight
-**********************
+## Calibration by Weight
 
-.. image:: weight.png
-   :scale: 50%
-   :align: center
-   :alt: Calibration by Weight Screen
+```{image} weight.png
+:align: center
+:alt: Calibration by Weight Screen
+:scale: 50%
+```
 
 Since some beverages may have a specific gravity other than 1.000, and we measure by volume, adjustment of the measure taking into account the SG is possible.  If you are unsure of what to use, 1.015 is a good middle of the road number for most homebrewed beer.  If you leave it blank, the calibration employs 1.000 (water equivalence).
 
@@ -42,7 +42,6 @@ As you draw a beverage during calibration, the Pulses field will update with the
 
 When you are satisfied, use the Set PPG/PPL button to lock in the calibration. If you wish to reset the calculation back to its default, use the Reset button instead of saving. The pulses collected will be debited according to the new rate if you save, or the previously configured rate if you reset.
 
-Tap Setup
-*********************
+## Tap Setup
 
-See the :ref:`Taps <taps>` settings page for other tap settings.
+See the {ref}`Taps <taps>` settings page for other tap settings.

docs/context/settings/advanced/reset/index.rst → docs/context/settings/advanced/reset/index.md

@@ -1,11 +1,11 @@
-.. _reset:
+(reset)=
 
-Reset Controller
-################
+# Reset Controller
 
-.. image:: reset.png
-   :scale: 50%
-   :align: center
-   :alt: Reset Controller
+```{image} reset.png
+:align: center
+:alt: Reset Controller
+:scale: 50%
+```
 
 Clicking the "Reset Controller" button in this UI will perform the same function as pressing the reset button on the controller. The controller will retain all settings.

docs/context/settings/advanced/update/index.rst → docs/context/settings/advanced/update/index.md

@@ -1,20 +1,21 @@
-.. _update:
+(update)=
 
-Update Controller
-########################
+# Update Controller
 
-.. image:: update.png
-   :scale: 21%
-   :align: center
-   :alt: Check Versions
+```{image} update.png
+:align: center
+:alt: Check Versions
+:scale: 21%
+```
 
 This page will display the currently installed version as well as any available version og the firmware and filesystem.  In almost every case, teh versions of firmware and filesystem should match.  If they are different, it may be an indication of a failed updat.
 
 Pressing the "Update Firmware" button on this page will queue an update of the system application and website. The system will retain your configuration settings during the process.
 
-.. image:: in-progress.png
-   :scale: 50%
-   :align: center
-   :alt: Do Update
+```{image} in-progress.png
+:align: center
+:alt: Do Update
+:scale: 50%
+```
 
 The process will take five or more minutes, depending upon your network configuration. When complete, the page will refresh to the home page.

docs/context/settings/advanced/wifi/index.rst → docs/context/settings/advanced/wifi/index.md

@@ -1,18 +1,19 @@
-.. _resetwifi:
+(resetwifi)=
 
-Reset WiFi
-##############
+# Reset WiFi
 
-.. image:: wifi.png
-   :scale: 50%
-   :align: center
-   :alt: Reset WiFi
+```{image} wifi.png
+:align: center
+:alt: Reset WiFi
+:scale: 50%
+```
 
 If you plan to move your Keg Cop to a new location or connect to a new network, resetting the network settings ahead of time is a good idea.  Pressing the "Reset WiFi" button is an irreversible action and will delete the current WiFi configuration.
 
-.. image:: done.png
-   :scale: 50%
-   :align: center
-   :alt: WiFi Reset
+```{image} done.png
+:align: center
+:alt: WiFi Reset
+:scale: 50%
+```
 
 After this action, you will need to reconnect to the *kegcop* access point to reconfigure the WiFi settings.

docs/context/settings/controller/index.md

@@ -0,0 +1,19 @@
+(controller)=
+
+# Controller Settings
+
+```{image} controller.png
+:align: center
+:alt: Controller Settings
+:scale: 50%
+```
+
+The Controller Settings page allows configuration of settings which control the top-level settings of the system:
+
+- **Host Name**: This is the network hostname, to which you will connect as  *\{hostname}*.local. Do not include the .local portion; the mDNS system will append this automatically.  This name must be unique on the network, or unexpected behavior may result.  Most computer systems and mobile devices support mDNS. For more information, please see the {ref}`mDNS FAQ <faq-mdns>`.
+- **Brewery Name**: This is displayed on the {ref}`main page <home>`. It concatenates with the Kegerator name, e.g., "*Taplist for Kegerator in Silver Fox Brewery.*"
+- **Kegerator Name**: This displays on the main page. It concatenates with the Brewery name, e.g., e.g., "*Taplist for Kegerator in Silver Fox Brewery.*" This name reports to any upstream system.
+- **Units**:
+  : - **Metric**: Volume reports in liters and milliliters, the temperature in degrees Celcius, and you will enter the flowmeter calibration in pulses per liter.
+    - **Imperial**: Volume reports in gallons and ounces, the temperature in degrees Fahrenheit, you will enter the flowmeter calibration in pulses per gallon.
+- **Solenoid Relay**: This will energize or de-energize a relay. This setting controls a solenoid or bank of solenoids to turn the beverage flow on or off. I have provided this point for convenience; I intend for an upstream system to control it.