Start mkdocs implementation

Author: TotalDwarf03

.github/workflows/deploy_mkdocs.yml

@@ -0,0 +1,33 @@
+# A GitHub Actions workflow to deploy MkDocs documentation to GitHub Pages on push to the master or main branch.
+---
+name: Deploy MkDocs
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: pip install poetry
+      - run: poetry install --only docs
+      - run: mkdocs gh-deploy --force

.mega-linter.yml

@@ -35,6 +35,9 @@ DISABLE_LINTERS:
   - TERRAFORM_TFLINT
   - TERRAFORM_TERRASCAN
 
+  # Disable due to poor configuration options
+  - ACTION_ACTIONLINT
+
 SHOW_ELAPSED_TIME: true
 
 FILEIO_REPORTER: false

Makefile

@@ -43,6 +43,10 @@ install:  ## Install the dependencies excluding dev.
 install-dev:  ## Install the dependencies including dev.
 	poetry install
 
+.PHONY: install-docs
+install-docs:  ## Install only the documentation dependencies
+	poetry install --only docs
+
 .PHONY: megalint
 megalint:  ## Run the mega-linter.
 	docker run --platform linux/amd64 --rm \

README.md

@@ -8,6 +8,7 @@ A Python utility used to archive old, unused GitHub repositories from an organis
   - [Table of Contents](#table-of-contents)
   - [Prerequisites](#prerequisites)
   - [Makefile](#makefile)
+  - [Documentation](#documentation)
   - [Development](#development)
   - [Running the Project](#running-the-project)
     - [Containerised (Recommended)](#containerised-recommended)
@@ -45,6 +46,24 @@ This repository makes use of a Makefile to execute common commands. To view all
 make all
 ```
 
+## Documentation
+
+This project uses [MkDocs](https://www.mkdocs.org/) for documentation. The documentation is located in the `docs` directory. To view the documentation locally, you can run the following commands:
+
+1. Install MkDocs and its dependencies:
+
+    ```bash
+    make install-docs
+    ```
+
+2. Serve the documentation locally:
+
+    ```bash
+    mkdocs serve
+    ```
+
+3. Open your web browser and navigate to `http://localhost:8000`.
+
 ## Development
 
 To work on this project, you need to:

docs/documentation.md

@@ -0,0 +1,67 @@
+# Documentation
+
+This site uses MkDocs to build its documentation and GitHub Pages for hosting.
+
+## Format
+
+Documentation within this project follows the following pattern:
+
+- A `README.md` for each component
+- A `/docs` folder for the project
+
+Each `README.md` should contain:
+
+- A description of what the component is/does
+- A list of any prerequisites
+- Setup instructions
+- Execution instructions
+- Deployment instructions
+
+The `/docs` folder should contain:
+
+- A description of what the project is
+- An overview of how the everything fits together in the project
+- An explanation of the tech stack
+- Details of the underlying dataset
+
+A majority of the information should reside within the `/docs` directory over the `README`. The `README`s in this project should be kept for concise instructions on how to use each component. Any detailed explanation should be kept within `/docs`.
+
+## Getting MkDocs Setup
+
+In order to build an MkDocs deployment or serve the documentation locally, we need to install MkDocs and its dependencies.
+
+1. Navigate into the project's root directory.
+
+2. Install MkDocs and its dependencies.
+
+    ```bash
+    make install-docs
+    ```
+
+3. You can now use MkDocs. To see a list of commands run the following:
+
+    ```bash
+    mkdocs --help
+    ```
+
+## Updating MkDocs Deployment
+
+### GitHub Action to Deploy Documentation
+
+A GitHub Action is set up to automatically deploy the documentation to GitHub Pages whenever a commit is made to the `main` branch. This action is triggered by a push event to the `main` branch and runs the `mkdocs gh-deploy` command to build and deploy the documentation.
+
+### Manual Deployment
+
+If changes are made within `/docs`, the GitHub Pages deployment will need to be updated. Assuming you have already installed [MkDocs](https://www.mkdocs.org/getting-started/#installation) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/getting-started/#installation), do the following:
+
+1. Navigate to the projects root directory.
+
+2. Deploy the documentation to GitHub Pages.
+
+    ```bash
+    mkdocs gh-deploy
+    ```
+
+3. This will build the documentation and deploy it to the `gh-pages` branch of your repository. The documentation will be available at `https://ONS-Innovation.github.io/<repository-name>/`.
+
+**Please Note:** The `gh-deploy` command will overwrite the `gh-pages` branch and make the local changes available on GitHub Pages. Make sure that these changes are appropriate and have been reviewed before deployment.

docs/index.md

@@ -0,0 +1 @@
+# GitHub Repository Archive Script

mkdocs.yml

@@ -0,0 +1,79 @@
+site_name: GitHub Repository Archive Script
+
+repo_url: https://github.com/ONS-Innovation/github-repository-archive-script
+repo_name: GitHub Repository Archive Script
+
+nav:
+  - Home: "index.md"
+  - FAQ: "faq.md"
+  - Documentation: "documentation.md"
+  - Technical Documentation:
+      - Overview: "technical-documentation/overview.md"
+      - The Process: "technical-documentation/the-process.md"
+      - Configuration: "technical-documentation/configuration.md"
+      - Notification Issue: "technical-documentation/notification-issue.md"
+      - Logging: "technical-documentation/logging.md"
+
+theme:
+  name: material
+  language: en
+
+  palette:
+    # toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: white
+      accent: deep purple
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+
+    # toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: white
+      accent: deep purple
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to system preference
+
+  features:
+    - navigation.tracking
+    - navigation.sections
+    - navigation.path
+    - navigation.top
+    - navigation.footer
+
+    - search.suggest
+
+    - header.autohide
+    - content.code.copy
+
+  logo: assets/logo.png
+  favicon: assets/favicon.ico
+
+  icon:
+    repo: fontawesome/brands/github
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python