Structure the new documentation

- Add support for multi-site documentation.
- Add workflow to deploy to GitHub Pages.

Author: RobertoPrevato

.github/workflows/main.yml

@@ -2,12 +2,17 @@ name: Main
 
 on:
   workflow_dispatch:
+    inputs:
+      publish_artifacts:
+        description: "Publish artifacts (Y|N)"
+        required: true
+        default: "N"
   release:
     types: [published]
   push:
     branches:
       - main
-      - v1
+      - dev
     paths-ignore:
       - README.md
   pull_request:
@@ -22,7 +27,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.11"]
+        python-version: ["3.13"]
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -41,71 +46,49 @@ jobs:
           pip install -U pip
           pip install -r requirements.txt
 
-      - name: Build documentation
+      - name: Build and pack docs
         run: |
-          mkdocs build
-
-      - name: Fix links
-        run: |
-          chmod +x ./fixlinks.sh
-          ./fixlinks.sh
-
-      - name: Zip built files
-        run: |
-          mkdir -p .build/blacksheep
-          mv site/* .build/blacksheep
-          cd .build
-          7z a -r site.zip blacksheep
+          ./pack.sh
 
       - name: Upload distribution package
-        uses: actions/upload-artifact@master
+        uses: actions/upload-artifact@v4
         with:
-          name: dist
-          path: .build/site.zip
+          name: site
+          path: site.zip
 
   publish:
+    if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish_artifacts == 'Y')
+    needs: build
     runs-on: ubuntu-latest
-    needs: [build]
-    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+
     steps:
-      - name: Download a distribution artifact
-        uses: actions/download-artifact@v2
+      - name: Checkout repository
+        uses: actions/checkout@v4
         with:
-          name: dist
-          path: dist
+          ref: gh-pages
+          path: neoteroi
 
-      - name: Unzip artifacts
-        run: |
-          7z x -o"site" dist/site.zip
-
-      - name: Use Python 3.10
-        uses: actions/setup-python@v4
+      - name: Download artifact
+        uses: actions/download-artifact@v4
         with:
-          python-version: "3.10"
+          name: site
+          path: site
 
-      - name: Install tools
+      - name: Unzip artifact
         run: |
-          pip install pyazblob
+          unzip site/site.zip -d site
 
-      - name: Publish distribution 📦 to DEV
+      - name: Deploy to gh-pages branch
         run: |
-          pyazblob upload --path site/ --account-name "$ACCOUNT_NAME" -cn "\$web" -r -f
-        env:
-          ACCOUNT_NAME: ${{ secrets.DEV_EUW_ACCOUNT_NAME }}
-          PYAZ_ACCOUNT_KEY: ${{ secrets.DEV_EUW_ACCOUNT_KEY }}
+          find neoteroi -mindepth 1 ! -name '.git' ! -name 'CNAME' ! -name 'README.md' ! -path 'neoteroi/.git/*' -exec rm -rf {} +
+          cp -r site/site/* neoteroi/
 
-      - name: Publish distribution 📦 to PROD EUW
-        if: github.ref == 'refs/heads/main'
-        run: |
-          pyazblob upload --path site/ --account-name "$ACCOUNT_NAME" -cn "\$web" -r -f
-        env:
-          ACCOUNT_NAME: ${{ secrets.PROD_EUW_ACCOUNT_NAME }}
-          PYAZ_ACCOUNT_KEY: ${{ secrets.PROD_EUW_ACCOUNT_KEY }}
+          cd neoteroi
+          git config user.name "${GITHUB_ACTOR}"
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
 
-      - name: Publish distribution 📦 to PROD USE
-        if: github.ref == 'refs/heads/main'
-        run: |
-          pyazblob upload --path site/ --account-name "$ACCOUNT_NAME" -cn "\$web" -r -f
-        env:
-          ACCOUNT_NAME: ${{ secrets.PROD_USE_ACCOUNT_NAME }}
-          PYAZ_ACCOUNT_KEY: ${{ secrets.PROD_USE_ACCOUNT_KEY }}
+          git add .
+          git commit -m "Deploy documentation on $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
+
+          git push origin gh-pages
+          echo "Published to gh-pages"

.gitignore

@@ -1,7 +1,13 @@
 site
-
 venv
-
 .build
-
 .env
+site.zip
+deploy
+out
+.local
+
+# temporary
+rodi
+shared-assets
+copy-shared.sh

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Neoteroi, Roberto Prevato (roberto.prevato@gmail.com)
+Copyright (c) 2021 Roberto Prevato (roberto.prevato@gmail.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -1,29 +1,35 @@
-[![Main](https://github.com/Neoteroi/BlackSheep-Docs/actions/workflows/main.yml/badge.svg)](https://github.com/Neoteroi/BlackSheep-Docs/actions/workflows/main.yml)
+# Neoteroi documentation 📜
 
-# BlackSheep documentation 📜
 This repository contains the source code of the documentation that gets
-published to [https://www.neoteroi.dev/blacksheep/](https://www.neoteroi.dev/blacksheep/).
+published to [https://www.neoteroi.dev/](https://www.neoteroi.dev/).
 
-This code has been previously hosted in [Azure DevOps](https://dev.azure.com/robertoprevato/BlackSheep).
+---
+
+Work in progress. 🚧
+The code has been modified to unify different projects.
+
+---
 
 ## How to contribute
 
-The documentation uses MkDocs. For information on how to use MkDocs, refer to its
-documentation.
+The documentation uses MkDocs and Material for MkDocs. For information on how
+to use these tools, refer to their documentation.
 
 ```bash
 $ mkdocs serve
 ```
 
-### Environments
+## How to build the full site
 
-Documentation can be deployed to a DEV environment (this happens when a release is
-created from a branch different than `main`), or a PROD environment, when a release is
-created from the `main` branch.
+- Create a Python virtual environment, activate, install the dependencies.
+- Use `pack.sh` to build the full site.
+- `cd` into the generated `site` folder.
+- Start a dev servers. Recommended: use `Python http.server` module.
 
-* [DEV](https://neoteroideveuwstacc.z6.web.core.windows.net/blacksheep/)
-* [PROD](https://www.neoteroi.dev/blacksheep/)
+```bash
+./pack.sh
 
-The documentation for `blacksheep` is published under the path `/blacksheep/`
-because the same service will be used to serve documentation for other projects,
-like `rodi`.
+cd site
+
+python3.13 -m http.server 44777
+```

README.md

@@ -0,0 +1,24 @@
+.PHONY: build fixlinks
+include .env
+
+build:
+	mkdocs build
+	./fixlinks.sh
+	rm -rf .build
+	mkdir -p .build/blacksheep
+	mv site/* .build/blacksheep
+	echo "Ready to publish"
+
+
+build-v1:
+	mkdocs build
+	VERSION="v1" ./fixlinks.sh
+	rm -rf .build
+	mkdir -p .build/blacksheep/v1
+	mv site/* .build/blacksheep/v1
+	echo "Ready to publish"
+
+
+clean:
+	rm -rf site/
+	rm -rf .build/

banner.xcf

@@ -0,0 +1,3 @@
+# BlackSheep docs 📜
+
+[www.neoteroi.dev](https://www.neoteroi.dev/blacksheep/).

blacksheep/Makefile

@@ -0,0 +1,4 @@
+# Archived documentation
+
+This folder contains archived documentation of the web framework, not meant
+to be updated.