Initial Docs Layout and Deployment

.github/workflows/deploy_docs.yml

@@ -0,0 +1,28 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Test that docs build without error
+        if: github.event_name == 'pull_request'
+        run: uv run mkdocs build --strict
+
+      - name: Deploy docs to GitHub Pages
+        if: github.event_name == 'push'
+        run: uv run mkdocs gh-deploy --strict --force

.python-version

@@ -0,0 +1 @@
+3.13

docs/docs_setup.md

@@ -0,0 +1,92 @@
+# Creating documentation with uv and MkDocs
+
+For preparing documentation, we will use [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/). The Material theme is first class for MkDocs, and in fact many plugins are set up for Material and not the default MkDocs theme.
+
+## Get MkDocs locally
+
+```bash
+uv init
+uv add mkdocs-material
+```
+
+or
+
+```bash
+uv pip install mkdocs-material
+```
+
+## Initialize a new MkDocs project
+
+```bash
+uv run mkdocs new .
+uv run mkdocs serve
+```
+
+Follow the [setup instructions](https://squidfunk.github.io/mkdocs-material/creating-your-site/) from mkdocs-material.
+
+## Create Documentation Locally
+
+Add documentation to `docs/`. Save, and watch a live update in your browser.
+
+Make commits and push to your repo, preferably with a PR. (See [Recommended Github Repo Settings](gh_repo_settings.md) for more details on how to set up your repo.)
+
+To build the documentation locally, use
+
+```bash
+uv run mkdocs build
+```
+
+And it will create a `site/` directory with the built documentation.
+
+While you *can* manage a static site by locally building and uploading the `site/` directory, it is much easier to use a service like [GitHub Pages](https://pages.github.com/) or [Read the Docs](https://readthedocs.org/) to host your documentation. For this reason, I add `site/` to `.gitignore` so that it is not committed to the repo.
+
+## Deploy Documentation
+
+Instead of building the docs locally, we will use GitHub Actions to build and deploy the documentation.
+
+MkDocs provides a way to manually deploy to GitHub Pages `mkdocs gh-deploy`, but again, this requires local management *and* goes against the ethos of using PRs to manage changes to the codebase.
+
+Instead, we will use a GitHub Action to automatically build the documentation in PRs and commits to main, and deploy the docs to GitHub Pages when a PR is merged to main. MkDocs-Materials provides an action to do this, which is documented in the [MkDocs-Material documentation](https://squidfunk.github.io/mkdocs-material/publishing-your-site/), but we will use a custom action.
+
+First, create a `.github/workflows/` directory in your repo. Then, create a file called `deploy_docs.yml` in that directory with the following content:
+
+```yaml
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: write
+
+concurrency:
+  name: Cancel in-progress jobs for same trigger
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Test that docs build without error
+        if: github.event_name == 'pull_request'
+        run: uv run mkdocs build --strict
+
+      - name: Deploy docs to GitHub Pages
+        if: github.event_name == 'push'
+        run: uv run mkdocs gh-deploy --strict --force
+
+```
+
+Now, when you create a PR the docs will be tested to ensure they build without error. When you merge a PR to main, the docs will be built and deployed to GitHub Pages.
+
+While writing this, I got the error in my [action on the PR](https://github.com/TimMonko/urssi-docs/actions/runs/16708940401/job/47291006777?pr=1). Helpful!
+
+```bash
+WARNING -  Doc file 'docs-setup.md' contains a link 'docs/gh_repo_settings.md', but the target is not found among documentation files.
+```

docs/gh_repo_settings.md

@@ -0,0 +1,50 @@
+# Recommended Github Repo Settings
+
+## Using Pull Requests to Document Code Change History
+
+Use pull requests for all changes to the codebase. Not only does this make changes safer, especially with regards to CI checks, but it also provides a clear history of changes made to the codebase. This is particularly useful for understanding the evolution of the code because it allows you to see what changes were made, when, and by whom. More than just `git blame`, many IDEs provide a way to view the history of the PR, including the discussions and commits that led to the final merged PR. This is invaluable not only for remembering your own work, but for documenting the codebase for others. *Even if you are working on a project alone, using a PR approach will prove invaluable at times.*
+
+A few recommendations to optimize this process:
+
+## General Repo Settings
+
+Use only Squash and Merge to keep a clean commit history. Use PR title and description to document the merge commit. Again, blame will allow you to find the PR and its discussion. 
+
+![Github Pull Request Settings](assets/gh-pr-settings.png)
+
+You may also like:
+
+- Always suggest updating pull request branches: Adds a button to update a PR with content from main -- useful for new contributors.
+- Automaticly delete head branches: Automatically deletes the branch after merging a PR.
+
+## Branch Protection Rules
+
+Set up branch protection rules to ensure that the main branch is protected from direct pushes, especially when you may accidentally push and break things that people rely on! Instead require all changes to go through a PR.
+
+In Repo Settings -> Rulesets.
+
+1. Name and activate a ruleset
+2. Protect the default branch and add the `gh-pages` branch if using for docs.
+3. Leave on the default settings
+4. Turn on "Require a pull request before merging". Use settings appropriate for yourself or team.
+5. Read through the rest of the settings and determine if they are appropriate for your project.
+
+Trying to push to main will result in
+
+```bash
+C:\Users\Tim\teaching\urssi-docs>git push
+Enumerating objects: 14, done.
+Counting objects: 100% (14/14), done.
+Delta compression using up to 12 threads
+Compressing objects: 100% (10/10), done.
+Writing objects: 100% (13/13), 58.66 KiB | 8.38 MiB/s, done.
+Total 13 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
+remote: error: GH013: Repository rule violations found for refs/heads/main.
+remote: Review all repository rules at https://github.com/TimMonko/urssi-docs/rules?ref=refs%2Fheads%2Fmain
+remote:
+remote: - Changes must be made through a pull request.
+remote:
+To https://github.com/TimMonko/urssi-docs.git
+ ! [remote rejected] main -> main (push declined due to repository rule violations)
+error: failed to push some refs to 'https://github.com/TimMonko/urssi-docs.git'
+```

docs/index.md

@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from urssi-docs!")
+
+
+if __name__ == "__main__":
+    main()

mkdocs.yml

@@ -0,0 +1,4 @@
+site_name: 2025 URSSI Docs
+site_url: https://timmonko.github.io/urssi-docs/
+theme:
+  name: material

pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "urssi-docs"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "mkdocs-material>=9.6.16",
+]