added some scripts for manual building

Author: Hecatron

README.md

@@ -1,7 +1,22 @@
+
 # Documentation
 
 This repo contains the official documentation for Hackspace Manchester. 
 
 All members can push edits or new documentation to this repo and it will automatically build and will be available at https://docs.hacman.org.uk
 
 This uses Github Actions and MKDocs
+
+## Build Process
+
+### Automated Build
+
+For most folks they only want to add pages or images via Github so are not interested in how the main page is built.
+However for those interested the documentation pages are built into a site using mkdocs and the mkdocs material theme using a ci script
+[.github\workflows\ci.yml](.github\workflows\ci.yml)
+
+## Manual Build
+
+If you want to experiment manually building the documentation for experimenting with plugins etc. There's a script in the root directory called **build.py** which can be used with python 3.8 / mkdocs / mkdocs material / any other plugins required.
+
+There's also a **virtenv** directory that can be used to setup a virtual python environment.

build.py

@@ -0,0 +1,81 @@
+#! python3
+import os, sys, subprocess, shutil
+
+# MkDocs Build Script
+class MkDocsBuild(object):
+
+    # Class Init
+    def __init__(self):
+        self.SRCDIR = "docs"
+        self.BUILDDIR = "site"
+        self.MKDOCSDIR = "./"
+
+    # Run a command
+    def run_cmd(self, cmdarray, workingdir):
+        proc = subprocess.Popen(cmdarray, cwd=workingdir, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True)
+        proc_out, proc_err = proc.communicate()
+        print(proc_out)
+        print(proc_err)
+        if proc.returncode != 0:
+            raise RuntimeError("Failure to run command")
+        return
+
+    # Empty a directory
+    def emptydir(self, top):
+        if(top == '/' or top == "\\"): return
+        else:
+            for root, dirs, files in os.walk(top, topdown=False):
+                for name in files:
+                    os.remove(os.path.join(root, name))
+                for name in dirs:
+                    os.rmdir(os.path.join(root, name))
+
+    # Print Usage
+    def usage(self):
+        print ("Please use build.py <target> where <target> is one of")
+        print ("  build       to build the standalone HTML files into the " + self.BUILDDIR + " directory")
+        print ("  clean       to clean the output directory:" + self.BUILDDIR)
+        print ("  publish     publish the site to the gh-pages branch")
+        print ("  serve       Serve the site out on a port for previewing")
+
+    # Do the main build of doxygen html
+    def build(self):
+        self.clean()        
+        print("Building MkDocs Files")
+        cmdopts = ["mkdocs", "build", "--clean"]
+        self.run_cmd(cmdopts, self.MKDOCSDIR)
+        print ("Build finished. The HTML pages are in " + self.BUILDDIR)
+
+    # Publish the Site
+    def publish(self):
+        print("Publishing MkDocs Files")
+        cmdopts = ["mkdocs", "gh-deploy"]
+        self.run_cmd(cmdopts, self.MKDOCSDIR)
+        print ("Publish finished.")
+
+    def serve(self):
+        print("Starting MkDocs Server http://127.0.0.1:8000")
+        cmdopts = ["mkdocs", "serve"]
+        self.run_cmd(cmdopts, self.MKDOCSDIR)
+        print ("Server Closed.")
+
+    # Clean the Build directory
+    def clean(self):
+        self.emptydir("site")
+        print ("Clean finished")
+
+    def main(self):
+        if len(sys.argv) != 2:
+            self.usage()
+            return
+        if sys.argv[1] == "build":
+            self.build()
+        if sys.argv[1] == "clean":
+            self.clean()
+        if sys.argv[1] == "publish":
+            self.publish()
+        if sys.argv[1] == "serve":
+            self.serve()
+
+if __name__ == "__main__":
+    MkDocsBuild().main()

test.md

@@ -0,0 +1,5 @@
+# Ignore tox dirs
+.tox-dev/
+
+# Ignore python virtual environment directory
+py38dev/

virtenv/.gitignore

@@ -0,0 +1,10 @@
+# Readme
+
+## Python Virtual Environment
+
+If you have **python 3.8** and **tox** installed
+you can use the scripts in this directory to setup a virtual python environment
+
+  * **setup_venv.bat** - Setup a virtual python environment under Windows
+  * **setup_venv.sh** - Setup a virtual python environment under Linux / Unix
+

virtenv/Readme.md

@@ -0,0 +1,3 @@
+# Depends
+mkdocs
+mkdocs-material

virtenv/dev_requirements.txt

@@ -0,0 +1,20 @@
+@echo off
+SETLOCAL
+
+set "venv=%1"
+if "%venv%" == "" ( set "venv=py38dev" )
+
+IF EXIST "%venv%" (
+    echo "Entering virtual environment %venv%"
+    echo "use deactivate to leave"
+    cmd /k "%venv%\Scripts\activate.bat"
+
+) ELSE (
+    echo "Creating virtual environment %venv%"
+    tox -c tox_dev.ini
+    echo "Entering virtual environment %venv%"
+    echo "use deactivate to leave"
+    cmd /k "%venv%\Scripts\activate.bat"
+)
+
+ENDLOCAL

virtenv/setup_venv.bat

@@ -0,0 +1,20 @@
+#! /bin/bash
+
+if [ -z "$1" ]
+then
+      venv=$1
+else
+      venv="py38dev"
+fi
+
+if [ ! -d "./$venv" ]; then
+  echo "Creating virtual environment $venv"
+  tox -c tox_dev.ini
+  source $venv/bin/activate
+fi
+
+# Enter the python virtual enviro on the current shell
+echo "Entering virtual environment $venv"
+bash --rcfile <(echo '. ./py37dev/Scripts/activate')
+
+# use echo $BASHPID to check the bash prompt process id

virtenv/setup_venv.sh

@@ -0,0 +1,21 @@
+# Tox file for setting up python virtual environments for development
+
+# To setup all use "tox -c tox_dev.ini"
+# To setup an individual environment "tox -c tox_dev.ini -e py37"
+
+[tox]
+minversion = 3.0
+skipsdist=True
+setupdir = {toxinidir}/..
+distdir = {toxinidir}/.tox-dev/distshare
+toxworkdir = {toxinidir}/.tox-dev
+
+# List of environments
+# make sure to update environment list in travis.yml and appveyor.yml
+envlist =
+    py38
+
+# Python 3.8 Development environment
+[testenv:py38]
+envdir = py38dev
+deps = -rdev_requirements.txt