Merge pull request #52 from Free60Project/fix/strict_mkdocs

Stricter mkdocs, Docker deployment, CI separation, README additions

Author: InvoxiPlayGames

.github/workflows/build.yml

@@ -1,16 +1,18 @@
-name: Build and Deploy
-on:
-  push:
-    branches:
-      - master
+name: Build site
+on: [push, pull_request]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout master
-        uses: actions/checkout@v2.4.0
-      - name: Deploy MkDocs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Install python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Install deps
+        run: pip install -U -r requirements.txt
+      - name: Build
+        run: mkdocs build --strict

.github/workflows/deploy.yml

@@ -0,0 +1,39 @@
+name: Deploy Website
+on:
+  push:
+    branches:
+      - master
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: pip install -U -r requirements.txt
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'site'
+      - id: deployment
+        if: github.ref_name == 'master'
+        uses: actions/deploy-pages@v4

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.11-alpine
+
+RUN apk add git
+
+WORKDIR /wiki
+COPY requirements.txt .
+RUN pip install -U -r requirements.txt
+
+# Force /wiki directory to be considered safe for git
+RUN git config --global --add safe.directory /wiki
+
+RUN echo $'#!/bin/sh\n\
+    cd /wiki\n\
+    mkdocs serve -a $(hostname -i):8000 --strict' > /docker-entrypoint.sh
+
+RUN chmod +x /docker-entrypoint.sh
+
+ENTRYPOINT ["/docker-entrypoint.sh"]

Makefile

@@ -1,7 +1,7 @@
 build: ## Build docs locally
-	mkdocs build --clean
+	mkdocs build --strict --clean
 
 serve: ## Serve live version of your docs
-	mkdocs serve
+	mkdocs serve --strict
 
 all: build

README.md

@@ -16,7 +16,7 @@ Contributions are very welcome. Here's how you can help:
 - Correct spelling / grammar
 - Fix links
 
-### Workflow
+## Workflow
 
 1. __Fork__ this repo
 1. Make changes
@@ -26,6 +26,7 @@ Contributions are very welcome. Here's how you can help:
 ### Step by step instructions
 
 **NOTE**: The following instructions are targeted towards Unix OS' - needed steps on windows may vary.
+
 **NOTE 2**: You need python3 and python3-venv installed. Please look at your OS' package manager to find the correct packages.
 
 1. At first: Fork the repository to your account!
@@ -42,41 +43,22 @@ or
 git clone https://github.com/<username>/wiki.git
 ```
 
-3. Prepare your python virtual environment and dependencies
+3. Navigate into wiki repository folder
 
 ```sh
-# Navigate to the cloned repo
 cd wiki/
-
-# Create a python3 virtual environment in your cloned repository
-python -m venv venv
-
-# Activate the virtual environment
-source venv/bin/activate
 ```
 
-4. Install needed python dependencies using python package manager -> pip
+4. Choose one of the two deployment methods below.
 
 ```sh
 pip install mkdocs mkdocs-material mkdocs-redirects
 ```
 
-5. At this point, load up the clone repository in a text editor that has live-markdown preview function.
+5. At this point, load up the cloned repository in a text editor that has live-markdown preview function.
   - For example: Visual Studio Code. Instructions: (https://code.visualstudio.com/Docs/languages/markdown)
 
-6. When you are done, use the following steps to build & preview the documentation / changes locally.
-
-Build the documentation
-```sh
-make build
-```
-
-Serve the documentation
-```sh
-make serve
-```
-
-7. Once you are happy and the added changes are looking proper, you are ready to submit your work.
+6. Once you are happy and the added changes are looking proper, you are ready to submit your work.
 
 Add modified files for commiting
 ```sh
@@ -100,3 +82,44 @@ git push
 ```
 
 8. Send a Pull Request :)
+
+## Deployment / Usage of mkdocs
+
+### Native deployment
+
+1. Create & activate python virtual-environment (might need dependency `python3-venv`, see: <https://docs.python.org/3/library/venv.html>)
+
+```
+python3 -m venv venv
+source venv/bin/activate
+```
+
+2. Install mkdocs and dependencies
+
+```
+pip install -r requirements.txt
+```
+
+3. Edit docs and verify with the following commands:
+
+Serve the documentation (<http://127.0.0.1:8000>)
+```
+mkdocs serve --strict
+```
+
+Build the documentation
+```
+mkdocs build --strict
+```
+
+### Docker deployment
+
+1. Execute docker container:
+
+```
+docker compose up
+```
+
+2. Navigate to <http://127.0.0.1:8000>
+3. Make your changes and verify the formatting / linking still checks out.
+

docker-compose.yml

@@ -0,0 +1,10 @@
+version: "3"
+
+services:
+  wiki:
+    build:
+      context: .
+    ports:
+      - "127.0.0.1:8000:8000"
+    volumes:
+      - ./:/wiki

docs/!Pages_That_Need_Updates.md

@@ -2,11 +2,11 @@
 
 Some pages need edits to remain useful or become more beautiful.
 
-- [STFS](/System-Software/Formats/STFS) needs the base sequence written up
+- [STFS](./System-Software/Formats/STFS.md) needs the base sequence written up
   - halotroop2288 is working on this!
   - https://github.com/halotroop2288/kaitai_struct_formats/blob/pr/xbox/filesystem/stfs.ksy
-- [XCP](/System-Software/Formats/XCP) needs a full file format spec written up for it.
+- [XCP](./System-Software/Formats/XCP.md) needs a full file format spec written up for it.
   - halotroop2288 is working on this!
   - https://gitlab.com/0x8081/libxcp/-/blob/main/src/xcp.h
   - https://gitlab.com/0x8081/libxcp/-/blob/main/src/xcp.c
-- [XConfig](/System-Software/Formats/XConfig)'s spec (Notes section) should be converted to a markdown table.
+- [XConfig](./System-Software/XConfig.md)'s spec (Notes section) should be converted to a markdown table.

docs/!Pages_with_missing_images.md

@@ -1,5 +1,5 @@
 # Pages with missing images
 
-- [DVD Drive](Hardware/Console/DVD_Drive)
-- [NAND](Hardware/Console/NAND) "Atmel2.jpg"
-- [Wifi Adapter](Hardware/Accessories/Wifi_Adapter.md)
+- [DVD Drive](./Hardware/Console/DVD_Drive.md)
+- [NAND](./Hardware/Console/NAND/index.md) "Atmel2.jpg"
+- [Wifi Adapter](./Hardware/Accessories/Wifi_Adapter.md)

docs/Category_Template_documentation.md

@@ -1,5 +1,5 @@
 # Category: Template documentation
 
-[Old Main Page](/Old_Main_Page)
+[Old Main Page](./Old_Main_Page.md)
 
-[Other OS Loader](/Other_OS_Loader)
+[Other OS Loader](./Other_OS_Loader.md)

docs/Development/Cross_Compiler.md

@@ -1,9 +1,9 @@
 # Cross Compiler
 
-The Xbox 360 [CPU](../Xenon_(CPU)) is based on IBM's Power
+The Xbox 360 [CPU](../Hardware/Console/Xenon_(CPU).md) is based on IBM's Power
 Architecture. Unless you have a machine with PowerPC CPU and Linux
 running (such as an older Mac or a PS3), you need to set up a cross
-compiler toolchain in order to compile code like the [Linux Kernel](../Linux_Kernel)
+compiler toolchain in order to compile code like the [Linux Kernel](../Linux/Linux_Kernel.md)
 for your Xbox 360.
 
 A typical cross compiler toolchain for the GNU compiler collection
@@ -21,7 +21,7 @@ well.
 
 ## Using the Xenon Toolchain
 
-The easiest way to set up a complete cross compiler toolchain is the [Xenon Toolchain](../Xenon_Toolchain).
+The easiest way to set up a complete cross compiler toolchain is the [Xenon Toolchain](./Xenon_Toolchain.md).
 Its using current gcc and does not take as long as crossotool to compile.
 
 
@@ -70,7 +70,7 @@ cd crosstool-0.43/
 ./demo-powerpc-970.sh
 ```
 
-4. **Get a drink**, go for a walk or use the time to remove the resistor [R6T3](../R6T3)
+4. **Get a drink**, go for a walk or use the time to remove the resistor [R6T3](../Hardware/R6T3.md)
 from the mainboard of your Xbox 360... Compilation of your cross compiler will just take a while.
 
 5. **When finished**, you may want to add your cross compiler binaries to your PATH environment
@@ -80,6 +80,6 @@ variable.
 export PATH=$PATH:/opt/crosstool/gcc-4.1.0-glibc-2.3.6/powerpc64-unknown-linux-gnu/bin
 ```
 
-You're done. Feel free to configure and compile your [Linux Kernel](../Linux_Kernel).
+You're done. Feel free to configure and compile your [Linux Kernel](../Linux/Linux_Kernel.md).
+
 
-[Category: Development](/Development)