Documentation

.readthedocs.yaml

@@ -27,6 +27,6 @@ sphinx:
 # Optional but recommended, declare the Python requirements required
 # to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
+python:
+   install:
+   - requirements: docs/requirements.txt

README.md

@@ -1,35 +1,6 @@
 # Wat Kan Ik Doen webapp
 
-## Deployment Instructions
 
-### 1. Set up the database
-
-- Create a database and add the connection details to `.env`
-- Run migrations with `php artisan migrate`
-- Run seeders with `php artisan db:seed`
-
-### 2. Run the server
-
-- Run the server with `php artisan serve`
-
-### 3. Log in using the admin account
-
-- Log in with the username `[email protected]` and password `admin12345`. Change the password after logging in.
-
-## Modifying BREAD
-Configuration of the Voyager admin panel are saved in database tables. The defaults are seeded by files in `database/seeders`. Any changes need to be kept up to date in these seeders, to ensure easy deployment. 
-
-Reference for which seeder file (all in `database/seeders`) contains what:
-
-- `MenuItemsTableSeeder.php` -> Create new menu entries here
-- `DataTypesTableSeeder.php` -> Register BREAD for new tables here
-- `DataRowsTableSeeder.php` -> Configure the details for every field in said tables
-- `PermissionsTableSeeder.php` -> Add the BREAD permissions to table
-
-For new tables: 
-
-- Create a new seeder file for the table (see below on how to generate this)
-- Register the seeder file in `DatabaseSeeder.php`.
 
 ## Modifying settings
 This can be done at `/admin/settings`. It reads and writes to the `settings` table in the database. So, in order to preserve the settings for future deployments, make sure to update its seed with `php artisan iseed settings`.

docs/conf.py

@@ -0,0 +1,74 @@
+# Configuration file for the Sphinx documentation builder
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'Watkanikdoen.nl'
+copyright = '2024'
+author = 'Watkanikdoen.nl contributors'
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    # Sphinx's own extensions
+    "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    # External stuff
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinx_inline_tabs",
+]
+
+
+# -- Options for Autodoc --------------------------------------------------------------
+
+autodoc_member_order = "bysource"
+autodoc_preserve_defaults = True
+
+# Keep the type hints outside the function signature, moving them to the
+# descriptions of the relevant function/methods.
+autodoc_typehints = "description"
+
+# -- Options for extlinks ----------------------------------------------------
+#
+
+extlinks = {
+    "pypi": ("https://pypi.org/project/%s/", "%s"),
+}
+
+# -- Options for intersphinx -------------------------------------------------
+#
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+}
+
+# -- Options for TODOs -------------------------------------------------------
+#
+
+todo_include_todos = True
+
+# -- Options for Markdown files ----------------------------------------------
+#
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+myst_heading_anchors = 3
+
+# -- Options for HTML output -------------------------------------------------
+#
+
+html_theme = "furo"
+language = "en"
+
+# html_static_path = ["_static"]

docs/index.md

@@ -0,0 +1,13 @@
+---
+hide-toc: true
+---
+
+# Watkanikdoen.nl documentation
+
+
+```{toctree}
+:hidden:
+
+pages/getting-started
+pages/bread
+```

docs/pages/bread.md

@@ -0,0 +1,15 @@
+# BREAD
+
+Configuration of the Voyager admin panel are saved in database tables. The defaults are seeded by files in `database/seeders`. Any changes need to be kept up to date in these seeders, to ensure easy deployment. 
+
+Reference for which seeder file (all in `database/seeders`) contains what:
+
+- `MenuItemsTableSeeder.php` -> Create new menu entries here
+- `DataTypesTableSeeder.php` -> Register BREAD for new tables here
+- `DataRowsTableSeeder.php` -> Configure the details for every field in said tables
+- `PermissionsTableSeeder.php` -> Add the BREAD permissions to table
+
+For new tables: 
+
+- Create a new seeder file for the table (see below on how to generate this)
+- Register the seeder file in `DatabaseSeeder.php`.

docs/pages/getting-started.md

@@ -0,0 +1,27 @@
+# Getting started
+
+## Deployment Instructions
+
+### X. Install dependencies
+- PHP: Install PHP 8.2 and the required extensions 
+- NPM: 
+### X. Install PHP packages
+- Install composer (PHP package manager) using `sudo apt install composer`
+### X. Run a local MySQL database
+- 
+### 1. Set up the database
+- Create a database and add the connection details to `.env`
+- Run migrations with `php artisan migrate`
+- Run seeders with `php artisan db:seed`
+
+### X. Build the frontend
+- Run `npm install` to install the node packages
+- Run `npm run watch` to start the webpack compiler
+
+### 2. Run the server
+
+- Run the server with `php artisan serve`
+
+### 3. Log in using the admin account
+
+- Log in with the username `[email protected]` and password `admin12345`. Change the password after logging in.

docs/requirements.txt

@@ -0,0 +1,6 @@
+furo
+myst-parser
+sphinx-copybutton
+sphinx-design
+sphinx-inline-tabs
+sphinx-tabs

install-php.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# Update package lists
+sudo apt-get update
+
+# Install software-properties-common if not installed
+sudo apt-get install -y software-properties-common
+
+# Add ondrej/php which has PHP 8.2
+sudo add-apt-repository -y ppa:ondrej/php
+
+# Update package lists
+sudo apt-get update
+
+# Install PHP 8.2
+# Also install the extensions: GD, XML, and ZIP
+sudo apt-get install -y php8.2 php8.2-gd php8.2-xml php8.2-zip php8.2-mysql
+
+# Verify the installation
+php -v