Hellmerge #95 branch into 2.0-pre. #119

docs/clients.md

@@ -12,7 +12,7 @@ Various approaches exist to writing your own client, but in general:
 * Refer to the API docs. These are built on an OpenAPI definition file (`/static/apidocs/openapi.yml`), which you can
   automatically use to generate a client skeleton using various software.
 * Call the main "spots" or "alerts" API endpoints to get the data you want. For example, your app could call
-  `https://spothole.app/api/v1/spots` once every few minutes. Apply filters if necessary.
+  `https://spothole.app/api/v2/spots` once every few minutes. Apply filters if necessary.
 * Call the "options" API to get an idea of which bands, modes etc. the server knows about. You might want to do that
   first before calling the spots/alerts APIs, to allow you to populate your filters correctly.
 * Refer to the provided HTML/JS interface for a reference on different approaches. For example, the "alerts"/"upcoming"
@@ -25,15 +25,15 @@ once every two minutes, so if your client is interested in POTA data there's no
 than that.
 
 If you absolutely must be informed within seconds of a spot arriving in Spothole, please use the SSE endpoints instead,
-e.g. `https://spothole.app/api/v1/spots/stream`.
+e.g. `https://spothole.app/api/v2/spots/stream`.
 
 If you want to handle different types of spot or alert differently within your client, please consider making a single
 request to the Spothole API to retrieve all the data, then filtering on your side. For example, call
-`https://spothole.app/api/v1/spots?sig=POTA,SOTA` rather than making two separate calls to
-`https://spothole.app/api/v1/spots?sig=POTA` and `https://spothole.app/api/v1/spots?sig=SOTA`.
+`https://spothole.app/api/v2/spots?sig=POTA,SOTA` rather than making two separate calls to
+`https://spothole.app/api/v2/spots?sig=POTA` and `https://spothole.app/api/v2/spots?sig=SOTA`.
 
 Remember, here at Spothole Inc. we offer an industry-standard "five nines" uptime on our server, with our own unique
 twist: we don't tell you which side of the decimal point the nines start! (Translation: This is a hobby project.
 `spothole.app` runs on the same server as my blog and other stuff. It might go down without warning. By all means base
 your own project on data from the main server if you like, but if you want any control over reliability and downtime,
-please run your own copy instead.)
+please run your own copy instead.)

docs/docker.md

@@ -85,7 +85,7 @@ server {
     }
     
     # SSE endpoints
-    location ~ ^/api/v1/(spots|alerts)/stream/? {
+    location ~ ^/api/v2/(spots|alerts)/stream/? {
         proxy_pass http://spothole:8080;
         
         # Remove buffering, remove caching, add suitable timeouts for SSE API calls
@@ -147,4 +147,4 @@ server {
 
 If desired, you could even change the port on which Spothole runs from 8080 to a plain 80, in which case your
 `proxy_pass` statements could drop the `:8080` suffix. Since Spothole is in a container, it can serve HTTP on port 80
-if desired, because it doesn't conflict with the host system.
+if desired, because it doesn't conflict with the host system.

docs/modifying.md

@@ -9,12 +9,17 @@ To navigate your way around the source code, this list may help.
 
 *Python back-end code*
 
-* `/core` - Core classes and scripts
+* `/core` - Core classes and utilities
 * `/data` - Data storage classes
-* `/spotproviders` - Classes providing spots by accessing the APIs of other services
-* `/alertproviders` - Classes providing alerts by accessing the APIs of other services
-* `/solarconditionsproviders` - Classes providing solar and propagation by accessing the APIs of other services
+* `/providers/spot` - Classes providing spots by accessing the APIs of other services
+* `/providers/alert` - Classes providing alerts by accessing the APIs of other services
+* `/providers/solarconditions` - Classes providing solar and propagation by accessing the APIs of other services
+* `/providers/staticdata` - Classes providing static lookup data by accessing bundled data files or the APIs of other
+  services
+* `/providers/sigrefdata` - Classes providing SIG reference lookup data by accessing bundled data files or the APIs of
+  other services
 * `/server` - Classes for running Spothole's own web server
+* `spothole.py` - Main application script
 
 *Templates*
 
@@ -24,6 +29,7 @@ To navigate your way around the source code, this list may help.
 
 * `/static` - Root for static files served by the web server. These are all served from a path starting `/static/`.
 * `/static/apidocs` - Contains the OpenAPI spec (`openapi.yml`)
+* `/static/audio` - Audio files used by the web front-end
 * `/static/css` - CSS files used by the web front-end
 * `/static/img` - image files used by the web front-end
 * `/static/js` - JavaScript used by the web front-end
@@ -31,18 +37,18 @@ To navigate your way around the source code, this list may help.
 
 *Miscellaneous*
 
-* `/` - Main script (`spothole.py`), pip `requirements.txt`, config, README, etc.
+* `/` - pip `requirements.txt`, config, README, etc.
 * `/docs` - Documentation
 * `/images` - Image sources
-* `/datafiles` - Local data sources (differentiated from the majority of data files which are loaded from URLs and
-  cached in `/cache`)
-* `/cache` - Directory where static-ish data downloaded from the internet is cached to avoid rapid re-requests, and
-  where spot/alert data is cached so that it survives a software restart. Created on first run.
+* `/datafiles` - 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
+* `/cache` - Directory where Spothole stores all the data it uses that should be persisted to disk. Created on first
+  run.
 
 ### Extending the server
 
 Spothole is designed to be easily extensible. If you want to write your own spot provider, for example, simply add a
-module to the `spotproviders` package containing your class. (Currently, in order to be loaded correctly, the module (
+module to the `providers.spot` 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.)
 
 Your class should extend "SpotProvider"; if it operates by polling an HTTP Server on a timer, it can instead extend "
@@ -66,4 +72,5 @@ parameters are optional, but you will at least want to provide a `time` (which m
 Finally, simply add the appropriate config to the `spot_providers` section of `config.yml`, and your provider should be
 instantiated on startup.
 
-The same approach as above is also used for alert providers.
+The same approach as above is also used for alerts, and other types of providers. Give me a shout if you need any
+advice.

docs/nginx.md

@@ -48,7 +48,7 @@ server {
     }
     
     # SSE endpoints
-    location ~ ^/api/v1/(spots|alerts)/stream/? {
+    location ~ ^/api/v2/(spots|alerts)/stream/? {
         proxy_pass http://127.0.0.1:8080;
         
         # Remove buffering, remove caching, add suitable timeouts for SSE API calls
@@ -120,4 +120,4 @@ You should now be able to access the web interface by going to the domain from y
 
 Once that's working, [install certbot](https://certbot.eff.org/instructions?ws=nginx&os=snap) onto your server. Run it
 as root, and when prompted pick your domain name from the list. After a few seconds, it should successfully provision a
-certificate and modify your nginx config files automatically. You should then be able to access the site via HTTPS.
+certificate and modify your nginx config files automatically. You should then be able to access the site via HTTPS.

docs/running.md

@@ -47,7 +47,8 @@ python3 spothole.py
 ```
 
 The software can take a few seconds to start up, mostly because it is downloading an updated file to match callsigns to
-countries. This is normal, don't panic!
+countries. This is normal, don't panic! Once you see `You can access your copy of Spothole at
+http://localhost:8080` in the log, your server is good to go.
 
 If you see some errors on startup, check your configuration, e.g. in case you have specified a port for the web server
-that is already in use by something else.
+that is already in use by something else.