Merge pull request #554 from Lescurel/documentation-site

Documentation site: Adding MkDocs to generate Documentation

.github/workflows/documentation.yml

@@ -0,0 +1,47 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches: [master, main]
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12.6
+          cache: "pip"
+
+      - run: pip install mkdocs==1.6.1
+      - name: Build docs
+        shell: sh
+        run: mkdocs build
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action

docs/dev-guide/getting-started.md

@@ -0,0 +1,76 @@
+# Getting Started
+
+## Dependencies
+
+### Docker
+
+On a Debian based system (Ubuntu, Linux Mint, etc.), you can install docker with
+the package manager:
+
+```bash
+sudo apt-get install docker.io
+sudo adduser $(whoami) docker
+```
+
+You need to sign out and sign back in again for changes to take effect.
+
+### Python
+
+Makeradmin uses Python 3.11.
+
+```bash
+sudo apt-get install python3.11-dev python3.11-doc python3-pip
+```
+
+### npm
+
+Makeradmin uses nodejs 18 for a few components
+
+```bash
+sudo apt-get install npm
+```
+
+## Initialize everything
+
+Clone this git repository to a suitable place on your computer / server
+
+> Start by initializing and activating a [virtual python environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) in the cloned folder.
+> This makes sure that the packages used for Makeradmin are isolated into its own "environment" (i.e. in the local directory), and will not interfere with packages already installed.
+>
+>     $ python3 -m venv .venv
+>     $ source .venv/bin/activate
+
+Run the firstrun script
+
+```bash
+make firstrun
+```
+
+This will build docker images and configure the database. This may take quite some time.
+It will also generate a `.env` file with new random keys and passwords that the system will use.
+
+You will be prompted for if you want to create a new admin user, it is recommended to do this here.
+
+You will also be prompted for if you want to create some fake members, transactions etc which can be useful for development.
+
+If you are deploying on a server you need to configure hosts and other settings by editing the `.env` file.
+If you do modify the `.env` file you need to restart the services afterwards by running
+
+```bash
+docker-compose up -d --build
+```
+
+## Start MakerAdmin, web shop, etc.
+
+Run all services locally (but you will have to insert data, see below):
+
+```bash
+make run
+```
+
+You can also run in dev mode where source directories are mounted inside the containers and sources are
+reloaded when changed (in most cases):
+
+```bash
+make dev
+```

docs/index.md

@@ -0,0 +1,4 @@
+# Welcome to Makeradmin
+
+Maker admin is a project used by [Stockolm Makerspace](https://makerspace.se) to
+handle its member administration and its store.

docs/user-guide/getting-started.md

@@ -0,0 +1,3 @@
+# Getting Started with `makeradmin`
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum

mkdocs.yml

@@ -0,0 +1,7 @@
+site_name: Makeradmin
+nav:
+  - Home: index.md
+  - User Guide:
+      - Getting Started: user-guide/getting-started.md
+  - Developper Guide:
+      - Getting Started: dev-guide/getting-started.md