docs: integrate Git contributor avatars in user guide (#242)

Author: Djaytan

.github/workflows/docs-deploy.yml

@@ -31,6 +31,7 @@ jobs:
           egress-policy: block
           allowed-endpoints: >
             github.com:443
+            api.github.com:443
             pypi.org:443
             files.pythonhosted.org:443
 
@@ -53,6 +54,8 @@ jobs:
 
       - name: Build Site
         working-directory: docs/user-guide/
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }} # Avoid exceeding the GitHub API rate limits
         run: mkdocs build --strict
 
       - name: Upload artifact

.github/workflows/docs-validate.yml

@@ -31,6 +31,7 @@ jobs:
           egress-policy: block
           allowed-endpoints: >
             github.com:443
+            api.github.com:443
             pypi.org:443
             files.pythonhosted.org:443
 
@@ -53,4 +54,6 @@ jobs:
 
       - name: Build Site
         working-directory: docs/user-guide/
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }} # Avoid exceeding the GitHub API rate limits
         run: mkdocs build --strict

docs/user-guide/Dockerfile

@@ -3,6 +3,7 @@
 
 FROM docker.io/squidfunk/mkdocs-material:9.6.14@sha256:eb04b60c566a8862be6b553157c16a92fbbfc45d71b7e4e8593526aecca63f52
 
-# Add revisioning feature: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#revisioning
 RUN apk add --no-cache git && \
-    pip install mkdocs-git-revision-date-localized-plugin
+    pip install \
+      mkdocs-git-revision-date-localized-plugin \
+      mkdocs-git-committers-plugin-2

docs/user-guide/README.md

@@ -1,32 +1,61 @@
-# User Guide
+# 🧭 User Guide
 
-The user guide is made with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
+This user guide is built using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/), a modern static site generator designed for project
+documentation.
 
-## Prerequisites
+## ⚙️ Prerequisites
 
-The only prerequisite is to have [Docker](https://www.docker.com/) installed on your system.
+Before getting started, make sure the following tools are installed and properly configured:
 
-## Localdev
+* 🐳 [Docker](https://www.docker.com/)<br/>
+  Used to run the local development environment and build the documentation without installing Python or MkDocs directly on your machine.
+* 🧑‍💻 [GitHub CLI](https://cli.github.com/)<br/>
+  Required to authenticate with your GitHub account and generate a personal access token when needed. This is necessary because the `git-committers` MkDocs
+  plugin may hit the GitHub API's unauthenticated rate limit or require access to private repositories.<br/>
+  To authenticate, run:
+  ```bash
+  gh auth login
+  ```
+  Once authenticated, the GitHub CLI will provide the required token via `gh auth token`, which is used by the local development script when starting the
+  container.
 
-Run this command:
+## 🚀 Local Development
+
+To start the local development server, run:
 
 ```bash
 ./localdev.sh
 ```
 
-### ⚠️ Caveat
+### ⚠️ Important Note
+
+The logs might suggest accessing the preview at `http://0.0.0.0:8000/docker-papermc-server/`, but this will not work.
 
-Don't try to access the preview at `http://0.0.0.0:8000/docker-papermc-server/` as opposed to what may indicate logs.
-Doing so will result in a failure.
+Instead, open the site using one of the following URLs:
 
-Instead, use `http://localhost:8000/docker-papermc-server/` or `http://127.0.1:8000/docker-papermc-server/`.
+* `http://localhost:8000/docker-papermc-server/`
+* `http://127.0.0.1:8000/docker-papermc-server/`
 
-## Wrapper Script
+## 🛠 Wrapper Script
 
-To run `mkdocs` commands, use the `mkdocs.sh` script. For example:
+To run `mkdocs` commands manually, use the `mkdocs.sh` wrapper script. For example:
 
 ```bash
 ./mkdocs.sh build
 ```
 
-But it is recommended to use the `localdev.sh` script instead unless you know what you are doing.
+That said, unless you have a specific reason, it’s recommended to use `localdev.sh`, as it handles everything needed for local development.
+
+## ➕ Adding Dependencies
+
+When introducing new dependencies, make sure to update both the **local development environment** and the **CI build environment**, as they are managed
+separately.
+
+### 💻 Locally
+
+To update the local environment, open the `Dockerfile` and modify the `RUN pip install ...` line to include any additional packages you need.
+
+### 🤖 In CI
+
+Dependencies for the CI environment are declared in `requirements.in`. After editing this file to include the new packages, run the `requirements.sh` script.
+This will regenerate `requirements.txt`, which is the file actually used by the CI to install dependencies in a consistent and reproducible way.

docs/user-guide/mkdocs.sh

@@ -20,4 +20,8 @@ docker build -t squidfunk/mkdocs-material "${SCRIPT_DIR}"
 
 echo 'The preview is going to be available at http://localhost:8000/docker-papermc-server/'
 
-docker run --rm -it -p 8000:8000 --volume="${ROOT_PROJECT_DIR}:/docs" --workdir /docs/docs/user-guide --name mkdocs squidfunk/mkdocs-material "$@"
+docker run --rm -it -p 8000:8000 --name mkdocs \
+  --volume="${ROOT_PROJECT_DIR}:/docs" \
+  --workdir /docs/docs/user-guide \
+  -e MKDOCS_GIT_COMMITTERS_APIKEY="$(gh auth token)" \
+  squidfunk/mkdocs-material "$@"

docs/user-guide/mkdocs.yml

@@ -69,6 +69,9 @@ plugins:
   - search
   - git-revision-date-localized:
       enable_creation_date: true
+  - git-committers:
+      repository: Djaytan/docker-papermc-server
+      branch: main
 
 markdown_extensions:
   - admonition

docs/user-guide/requirements.in

@@ -1,2 +1,3 @@
 mkdocs-material
 mkdocs-git-revision-date-localized-plugin
+mkdocs-git-committers-plugin-2

docs/user-guide/requirements.txt

@@ -49,7 +49,9 @@ gitdb==4.0.12 \
 gitpython==3.1.44 \
     --hash=sha256:9e0e10cda9bed1ee64bc9a6de50e7e38a9c9943241cd7f585f6df3ed28011110 \
     --hash=sha256:c87e30b26253bf5418b01b0660f818967f3c503193838337fe5e573331249269
-    # via mkdocs-git-revision-date-localized-plugin
+    # via
+    #   mkdocs-git-committers-plugin-2
+    #   mkdocs-git-revision-date-localized-plugin
 idna==3.10 \
     --hash=sha256:12f65c9b470abda6dc35cf8e63cc574b1c52b11df2c86030af0ac09b01b13ea9 \
     --hash=sha256:946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3
@@ -83,12 +85,17 @@ mkdocs==1.6.1 \
     --hash=sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2 \
     --hash=sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e
     # via
+    #   mkdocs-git-committers-plugin-2
     #   mkdocs-git-revision-date-localized-plugin
     #   mkdocs-material
 mkdocs-get-deps==0.2.0 \
     --hash=sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c \
     --hash=sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134
     # via mkdocs
+mkdocs-git-committers-plugin-2==2.5.0 \
+    --hash=sha256:1778becf98ccdc5fac809ac7b62cf01d3c67d6e8432723dffbb823307d1193c4 \
+    --hash=sha256:a01f17369e79ca28651681cddf212770e646e6191954bad884ca3067316aae60
+    # via -r requirements.in
 mkdocs-git-revision-date-localized-plugin==1.4.7 \
     --hash=sha256:056c0a90242409148f1dc94d5c9d2c25b5b8ddd8de45489fa38f7fa7ccad2bc4 \
     --hash=sha256:10a49eff1e1c3cb766e054b9d8360c904ce4fe8c33ac3f6cc083ac6459c91953
@@ -148,7 +155,9 @@ pyyaml-env-tag==1.1 \
 requests==2.32.3 \
     --hash=sha256:55365417734eb18255590a9ff9eb97e9e1da868d4ccd6402399eaf68af20a760 \
     --hash=sha256:70761cfe03c773ceb22aa2f671b4757976145175cdfca038c02654d061d6dcc6
-    # via mkdocs-material
+    # via
+    #   mkdocs-git-committers-plugin-2
+    #   mkdocs-material
 six==1.17.0 \
     --hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274 \
     --hash=sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81