{% 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>

<p>The source code can be found at <a href="https://git.ianrenton.com/ian/spothole">https://git.ianrenton.com/ian/spothole</a>.
</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 %}