shore up docs

4 files changed, 45 insertions, 29 deletions

diff --git a/README.md b/README.md
index cdca181..6321c11 100644
--- a/README.md
+++ b/README.md
@@ -2,41 +2,39 @@
   -- Filename: README.md
   -- Startdate: 2022-02-11
   -->
-# Overview
-This is my proposed solution to my pastebin problem.
+# Readme for stackbin
+This project is a hard fork of a flask-based pastebin solution, intended for use on my production systems.
 
-# Features
+## Upstream
+[gitlab](https://gitlab.com/bgstack15/stackbin)
+
+## Features
 
 * Admin page which can list parents, children, and provide link to delete pastes.
 * Editable titles
 * "Reply to" pastes to make parent/children relationships
 * UUIDs instead of sequential integer ID numbers
 * Private pastes (accessible to admin, and to users with the whole link)
-* Reverse-proxy autoconfiguration by visiting /set
-
-# Using stackbin
-## Installing
+* Reverse-proxy autoconfiguration by visiting `/set`
 
-You can use flask for development servers, and uwsgi for production. For a production stack on CentOS 7:
+## Using stackbin
+### Installing
 
-    yum install nginx uwsgi uwsgi-logger-file python36-flask uwsgi-plugin-python36 python36-sqlalchemy python36-uwsgidecorators
-    pip3 install --user flask-sqlalchemy pytimeparse
+You can use flask for development servers, and uwsgi for production.
 
-## Instructions
+### Instructions
 
 Configure the application with these two files, based on the `.example` files available in the source code:
 
 * stackbin.conf
 * stackbin.wsgi.ini
 
-Generate new db.
-
-    python3 initdb.py
-
+#### Development
 Run server in development mode.
 
     FLASK_APP=stackbin.py FLASK_DEBUG=True flask run --host='0.0.0.0'
 
+#### Production
 Run the server in a full wsgi environment for the cleanup timer to operate.
 
     ./stackbin.bin
@@ -49,24 +47,30 @@ This means that if your app is behind `http://example.com/stackbin/` then you wo
 
     http://example.com/stackbin/set
 
-# Improvements
-I still need to work on these tasks:
+## Dependencies
+ For a production stack on CentOS 7:
 
-## Development
+    yum install nginx uwsgi uwsgi-logger-file python36-flask uwsgi-plugin-python36 python36-sqlalchemy python36-uwsgidecorators
+    pip3 install --user flask-sqlalchemy pytimeparse
 
-* Protect the /admin/ page
+## Improvements
+I still need to work on these tasks:
 
-## Release
+### Development
 
-* Deploy to prod
+* Protect the /admin/ page
 
-# Alternatives
+## Alternatives
 This is a very diverged fork of [su27/flask-pastebin](https://github.com/su27/flask-pastebin) which itself was a fork of the original [mitsuhiko/pastebin](https://github.com/mitsuhiko/flask-pastebin). The original had a few additional features worth reviewing.
 
-## Unresearched
+### Unresearched
 https://github.com/yasoob/logit-bin
 https://github.com/AWilliams17/PasteMate
 https://github.com/bsamadi/flask-pastebin
 
-## Attempted
+### Attempted
 https://github.com/Tygs/0bin sounds cool but it uses a stack I'm unfamiliar with and it had some issues and I didn't want to bother with it.
+
+## References
+
+1. Using UUIDs instead of integers in sqlite in SQLAlchemy: [https://stackoverflow.com/questions/183042/how-can-i-use-uuids-in-sqlalchemy/812363#812363](https://stackoverflow.com/questions/183042/how-can-i-use-uuids-in-sqlalchemy/812363#812363)
diff --git a/extra/stackbin.spec b/extra/stackbin.spec
index c5abeb8..505878d 100644
--- a/extra/stackbin.spec
+++ b/extra/stackbin.spec
@@ -45,14 +45,11 @@ Source1:    extra/%{name}.sysusers
 #Patch1:    extra/%%{name}-el7.patch
 #%%endif
 URL:        https://bgstack15.ddns.net/
-#Distribution:
-#Vendor:
 Packager:   B. Stack <bgstack15@gmail.com>
 Requires:   %{pythonver}-flask
 Requires:   %{pythonver}-sqlalchemy
 Requires:   %{pythonver}-uwsgidecorators
 Requires:   uwsgi-plugin-%{pythonver}
-# WORKHERE
 Requires:   uwsgi-logger-file
 %if 0%{?fedora}
 # Fedora has all the deps; no pip3 helper needed!
diff --git a/initdb.py b/initdb.py
index ba25591..65ca83e 100644
--- a/initdb.py
+++ b/initdb.py
@@ -1,3 +1,4 @@
+# Unnecessary now that stackbin runs db.create_all() by itself.
 from stackbin import db
 no_wsgi = True
 db.create_all()
diff --git a/stackbin.py b/stackbin.py
index ad5b047..653cb9b 100755
--- a/stackbin.py
+++ b/stackbin.py
@@ -1,8 +1,23 @@
 # File: stackbin.py
+# Location: http://gitlab.com/bgstack15/stackbin/
+# Authors: mitsuhiko, ofshellohicy, su27, bgstack15
 # SPDX-License-Identifier: GPL-3.0
-# Authors: mitsuhiko, su27, bgstack15
+# Startdate: 2011 by mitsuhiko
+# Title: Stackbin
+# Purpose: Flask-based pastebin
+# History:
+#    2014 ofshellohicy removed some features
+#    2016 su27 added some features
+#    2022 bgstack15 hard forked
 # Reference:
 #    fuss.py
+# Improve:
+# Dependencies:
+#    req-INCOMPLETE-devuan: python3-pytimeparse, python3-uwsgidecorators
+#    req-fedora: uwsgi, uwsgi-logger-file, python36-flask uwsgi-plugin-python36 python36-sqlalchemy, python36-uwsgidecorators, python3-pytimeparse, python3-uwsgidecorators
+#    req-centos7: uwsgi, uwsgi-logger-file, python36-flask uwsgi-plugin-python36 python36-sqlalchemy, python36-uwsgidecorators
+#    pip-centos7: flask-sqlalchemy, pytimeparse
+# Documentation: see README.md
 from datetime import datetime, timedelta
 from itsdangerous import Signer
 from flask import (Flask, request, url_for, redirect, g, render_template, session, abort)
@@ -17,7 +32,6 @@ except:
    print("Warning! Without uwsgidecorators, the cleanup timer cannot run.")
 import time
 
-## ripped from https://stackoverflow.com/questions/183042/how-can-i-use-uuids-in-sqlalchemy/812363#812363
 from sqlalchemy import types
 from sqlalchemy.dialects.mysql.base import MSBinary
 from sqlalchemy.schema import Column