Add a guide to contribution

Makefile

@@ -1,10 +1,19 @@
 prod: # execute this target on the production server in the nix-shell
-	rm -fr franklincce/staticfiles
 	cd franklincce; python3 manage.py collectstatic
-	sed "s/change_me/$(shell shuf -i1-1000000 -n1)/g" .env.prod.orig > .env.prod
+	sh gen_kb.sh
 	sed "s|change_me|$(shell dd if=/dev/urandom bs=1024 count=1|base64)|g" .env.prod.orig > .env.prod
 	docker-compose -f docker-compose.prod.yml up -d --build
 
-permissions:
+permissions: db.sqlite3
 	chmod -f 660 db.sqlite3
 	echo "make sure that db.sqlite3 is owned by group users"
+
+db.sqlite3:
+	touch db.sqlite3
+
+make_kb:
+	sh gen_kb.sh
+
+clean:
+	rm -fr franklincce/staticfiles
+	docker-compose -f docker-compose.prod.yml down -v

README.md

@@ -2,7 +2,48 @@ yig
 ===
 
 `yig` is a django app for exploring bills and resolutions in previous YMCA CCE conferences.
+It's sort of ballooned to also contain a knowledge-base thing.
 
-## licensing
+## Deploying in production
 
-see the `LICENSE.md` file
+0. Ensure that you have Docker installed and good to go.
+
+For NixOS machines, this involves the following:
+```nix
+{ ... }
+{
+    virtualisation.docker.enable = true;
+    users.users.<your user>.extraGroups = [ ... ] ++ [ "docker" ];
+}
+```
+
+1. Enter the `nix-shell`.
+2. `make permissions`
+3. `make`
+
+To tear down the docker container, type `make clean`.
+
+If you've just started the instance, you also need to configure a superuser.
+
+1. Run `docker ps | grep yig-web | awk -F' ' '{print $1}'` to get the container id
+2. Run `docker exec -it <container-id> bash` to get a shell.
+3. Run `python3 manage.py createsuperuser` and follow the prompts.
+
+## Usage
+
+In order to use the `explorer` component of this package, you need to add some legislative texts.
+These are in the form of PDFs -- they come from the YMCA CCE website or are sometimes emailed or otherwise shared with you.
+Only these PDFs will work because they follow a very specific format which the software exploits.
+
+1. Login with your admin account.
+2. Click on the `add` button next to `Legislation books` in the sidebar
+3. Upload your book, add a name, and choose the correct `Import strategy`
+4. Click save
+
+## More information
+
+More information about operation of this project can be found in the [knowledgebase](./kb) directory.
+
+## License
+
+`yig` is licensed under the AGPLv3 -- the terms of the license are available in [`LICENSE.md`](./LICENSE.md).

docker-compose.prod.yml

@@ -25,4 +25,3 @@ services:
       - web
 volumes:
   static_volume:
-  db_persist:

franklincce/explorer/admin.py

@@ -15,4 +15,3 @@ to_register = [
 ]
 for i in to_register:
     admin.site.register(*i)
-    print(i)

franklincce/explorer/templates/explorer/base.html

@@ -14,6 +14,7 @@
         <nav id="navbar" class="boxed">
             <div id="leftnav">
                 <a href="/explorer">explorer</a>
+                <a href="/kb">knowledge</a>
             </div>
             <div id="rightnav">
                 <a href="/explorer/all">all</a>

franklincce/franklincce/settings.py

@@ -11,6 +11,7 @@ https://docs.djangoproject.com/en/4.2/ref/settings/
 """
 
 import os
+import random
 
 from pathlib import Path
 
@@ -18,6 +19,9 @@ from pathlib import Path
 BASE_DIR = Path(__file__).resolve().parent.parent
 
 SECRET_KEY = os.environ.get("SECRET_KEY")
+if not SECRET_KEY:
+    print("[!!!] YOU'RE USING A RANDOM SECRET_KEY -- CHANGE THIS IF YOU'RE GOING INTO PROD")
+    SECRET_KEY = random.randint(1, 100000000000000)
 
 DEBUG = bool(os.environ.get("DEBUG", default=0))
 

gen_kb.sh

@@ -0,0 +1,10 @@
+files=$(find kb -type f | awk -F'/' '{print $NF}')
+IFS='
+'
+mkdir -p franklincce/staticfiles/kb
+
+for file in $files; do
+  	without_extension=${file%.*}
+    echo $file, $without_extension
+    pandoc -s --template=./template.html -f markdown -t html -o "franklincce/staticfiles/kb/$without_extension.html" "kb/$without_extension.md" --lua-filter=links-to-html.lua
+done

kb/CONTRIBUTING.md

@@ -1 +1,16 @@
-# todo
+---
+title: "Contributing to the knowledgebase"
+---
+
+1. If you haven't a GitHub account, [create one](https://github.com/signup) and sign in.
+2. Navigate to the `yig` repository in the VSCode Web Editor, or click [here](https://github.dev/stupidcomputer/yig)
+3. Click on the `kb/` directory on the sidebar.
+4. Select an article that you'd like to change.
+5. Make your changes.
+6. Click on the 'source control' tab on the left (the one that looks like a tree)
+7. Click the "plus" icon on all the entries in the left panel, and write a message explaining your changes, and then click "Commit and Push"
+8. You'll get a prompt to create your own "fork"; say yes.
+9. Navigate back to [Github](https://github.com) and click on the "yig" link in the upper left area.
+10. Click the "Compare and pull request" button, then scroll down and click "create pull request".
+
+Thanks for your contribution!

kb/index.md

@@ -0,0 +1,7 @@
+---
+title: "Franklin CCE Knowledgebase"
+---
+
+## Model UN
+
+- [Writing a resolution](./writing-resolution.md)

kb/writing-resolution.md

@@ -0,0 +1,5 @@
+---
+title: "Writing a Resolution"
+---
+
+This is a test

links-to-html.lua

@@ -0,0 +1,4 @@
+function Link(el)
+    el.target = string.gsub(el.target, "%.md", ".html")
+    return el
+end

nginx/nginx.conf

@@ -16,4 +16,8 @@ server {
     location /static/ {
         alias /home/app/web/staticfiles/;
     }
+
+    location /kb {
+        alias /home/app/web/staticfiles/kb;
+    }
 }

shell.nix

@@ -1,4 +1,4 @@
 { pkgs ? import <nixpkgs> {} }:
   pkgs.mkShell {
-    nativeBuildInputs = with pkgs.python311Packages; [ django pymupdf ] ++ [pkgs.docker-compose pkgs.gnumake] ;
+    nativeBuildInputs = with pkgs.python311Packages; [ django pymupdf ] ++ [ pkgs.docker-compose pkgs.gnumake pkgs.pandoc ] ;
   }

template.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+<meta charset="utf-8" />
+<meta name="generator" content="pandoc" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+<title>$title$</title>
+<link rel="stylesheet" href="/static/style.css">
+<link rel="stylesheet" href="/static/tn.css">
+</head>
+
+<body>
+    <nav id="navbar" class="boxed">
+        <div id="leftnav">
+            <a href="/explorer">explorer</a>
+            <a href="/kb">knowledge</a>
+        </div>
+    </nav>
+
+    <div class="boxed">
+        <h1>$title$</h1>
+        $body$
+    </div>
+</body>
+
+</html>