Rationalise docs part 4 #151

templates/help/usage/modifying.html

@@ -0,0 +1,78 @@
+{% extends "../help_page.html" %}
+{% block help_content %}
+
+<h2 class="mt-4 mb-4">Modifying the source code</h2>
+<p>Spothole is Public Domain licenced, so you can grab the source code and start modifying it for your own needs.
+Contributions of code back to the main repository are encouraged, but completely optional.</p>
+
+<h3 class="mt-4">Code structure</h3>
+<p>To navigate your way around the source code, this list may help.</p>
+
+<p><em>Python back-end code</em></p>
+<ul>
+    <li><code>/core</code> - Core classes and utilities</li>
+    <li><code>/data</code> - Data storage classes</li>
+    <li><code>/providers/spot</code> - Classes providing spots by accessing the APIs of other services</li>
+    <li><code>/providers/alert</code> - Classes providing alerts by accessing the APIs of other services</li>
+    <li><code>/providers/solarconditions</code> - Classes providing solar and propagation by accessing the APIs of other services</li>
+    <li><code>/providers/staticdata</code> - Classes providing static lookup data by accessing bundled data files or the APIs of other
+        services</li>
+    <li><code>/providers/callsign</code> - Classes providing callsign lookup data by accessing bundled data files or the APIs of other
+        services</li>
+    <li><code>/providers/activityrefdata</code> - Classes providing activity reference lookup data by accessing bundled data files or
+        the APIs of other services</li>
+    <li><code>/webserver</code> - Classes for running Spothole's own web server</li>
+    <li><code>/telnetserver</code> - Classes for running Spothole's telnet server</li>
+    <li><code>spothole.py</code> - Main application script</li>
+</ul>
+
+<p><em>Templates</em></p>
+<ul>
+    <li><code>/templates</code> - Templates used for constructing Spothole's user-targeted HTML pages</li>
+</ul>
+
+<p><em>HTML/JS/CSS front-end code</em></p>
+<ul>
+    <li><code>/static</code> - Root for static files served by the web server. These are all served from a path starting <code>/static/</code>.</li>
+    <li><code>/static/apidocs</code> - Contains the OpenAPI spec (<code>openapi.yml</code>)</li>
+    <li><code>/static/audio</code> - Audio files used by the web front-end</li>
+    <li><code>/static/css</code> - CSS files used by the web front-end</li>
+    <li><code>/static/img</code> - image files used by the web front-end</li>
+    <li><code>/static/js</code> - JavaScript used by the web front-end</li>
+    <li><code>/static/vendor</code> - Third-party libraries (CSS, JS, fonts and images)</li>
+</ul>
+
+<p><em>Miscellaneous</em></p>
+<ul>
+    <li><code>/</code> - pip <code>requirements.txt</code>, config, README, etc.</li>
+    <li><code>/docs</code> - Documentation</li>
+    <li><code>/images</code> - Image sources</li>
+    <li><code>/datafiles</code> - Local data files, used by some providers when the data will never change and/or is not easily available
+        online in a format Spothole can handle</li>
+    <li><code>/cache</code> - Directory where Spothole stores all the data it uses that should be persisted to disk. Created on first
+        run.</li>
+</ul>
+
+<h3 class="mt-4">Extending the server</h3>
+<p>Spothole is designed to be easily extensible. If you want to write your own spot provider, for example, simply add a
+module to the <code>providers.spot</code> package containing your class. (Currently, in order to be loaded correctly, the module
+(file) name should be the same as the class name, but lower case.)</p>
+<p>Your class should extend "SpotProvider"; if it operates by polling an HTTP Server on a timer, it can instead extend "
+HTTPSpotProvider" where some of the work is done for you.</p>
+<p>The class will need to implement a constructor that takes in the <code>provider_config</code> and provides it to the superclass
+constructor, while also taking any other config parameters it needs.</p>
+<p>If you're extending the base <code>SpotProvider</code> class, you will need to implement <code>start()</code> and <code>stop()</code> methods that start
+and stop a separate thread which handles the provider's processing needs. The thread should call <code>submit()</code> or
+<code>submit_batch()</code> when it has one or more spots to report.</p>
+<p>If you're extending the <code>HTTPSpotProvider</code> class, you will need to provide a URI to query and an interval to the
+superclass constructor. You'll then need to implement the <code>http_response_to_spots()</code> method which is called when new
+data is retrieved. Your implementation should then call <code>submit()</code> or <code>submit_batch()</code> when it has one or more spots to
+report.</p>
+<p>When constructing spots, use the comments in the Spot class and the existing implementations as an example. All
+parameters are optional, but you will at least want to provide a <code>time</code> (which must be timezone-aware) and a <code>dx_call</code>.</p>
+<p>Finally, simply add the appropriate config to the <code>spot_providers</code> section of <code>config.yml</code>, and your provider should be
+instantiated on startup.</p>
+<p>The same approach as above is also used for alerts, and other types of providers. Give me a shout if you need any
+advice.</p>
+
+{% end %}