diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f89fc906..b62c9172 100644 --- a/.readthedocs.yaml +++ b/.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 diff --git a/README.md b/README.md index 459c296a..3ce199b5 100755 --- a/README.md +++ b/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 `admin@admin.com` 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`. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..71f2d8c4 --- /dev/null +++ b/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"] \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..8fa64c73 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,13 @@ +--- +hide-toc: true +--- + +# Watkanikdoen.nl documentation + + +```{toctree} +:hidden: + +pages/getting-started +pages/bread +``` \ No newline at end of file diff --git a/docs/pages/bread.md b/docs/pages/bread.md new file mode 100644 index 00000000..3101879f --- /dev/null +++ b/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`. \ No newline at end of file diff --git a/docs/pages/getting-started.md b/docs/pages/getting-started.md new file mode 100644 index 00000000..8473f275 --- /dev/null +++ b/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 `admin@admin.com` and password `admin12345`. Change the password after logging in. \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..bb9039f4 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +furo +myst-parser +sphinx-copybutton +sphinx-design +sphinx-inline-tabs +sphinx-tabs \ No newline at end of file diff --git a/install-php.sh b/install-php.sh new file mode 100644 index 00000000..efc4405f --- /dev/null +++ b/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 \ No newline at end of file