setup mkdocs (#10)

Author: ritwiktiwari

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Build documentation
+        run: make docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

Makefile

@@ -1,4 +1,4 @@
-.PHONY: verify fix lint format type-check install test
+.PHONY: verify fix lint format type-check install test docs docs-serve
 
 # Verify - check everything without making changes
 verify: lint format-check type-check
@@ -23,8 +23,15 @@ type-check:
 
 # Install dependencies
 install:
-	uv sync --group dev
+	uv sync --all-groups
 
 # Run tests
 test:
 	uv run pytest tests/ -v
+
+# Documentation
+docs:
+	uv run --group docs mkdocs build
+
+docs-serve:
+	uv run --group docs mkdocs serve

README.md

@@ -1,4 +1,4 @@
-![Copier-Astral](static/copier-astral.png)
+![Copier-Astral](docs/static/copier-astral.png)
 
 ---
 
@@ -40,121 +40,9 @@ copier copy --trust /path/to/copier-astral my-project
 
 > **Note:** The `--trust` flag is required because this template uses custom Jinja2 extensions for features like auto-detecting git user info and generating slugified package names. These extensions are safe to use but Copier warns about them by default.
 
-## Getting Started with Your Generated Project
+## Documentation
 
-### 1. Initialize the repository and install dependencies
-
-```bash
-cd my-project
-git init -b main
-make install
-```
-
-### 2. Run the pre-commit hooks
-
-If you enabled pre-commit, install the hooks and run them to resolve any initial formatting issues:
-
-```bash
-pre-commit install
-uv run pre-commit run -a
-```
-
-### 3. Verify everything works
-
-```bash
-make verify
-make test
-```
-
-### 4. Create your GitHub repository and push
-
-```bash
-git add .
-git commit -m "init: generate project from copier-astral"
-git remote add origin git@github.com:YOUR_USERNAME/my-project.git
-git push -u origin main
-```
-
-> **Important:** If you enabled docs during setup, you must manually enable GitHub Pages in your repository. Go to **Settings → Pages → Source** and select **GitHub Actions**. Without this, the docs workflow will fail.
-
-### 5. Set up external services (optional)
-
-- **Codecov**: Add your `CODECOV_TOKEN` as a [repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository)
-- **PyPI**: Add your `PYPI_TOKEN` as a repository secret. See the [PyPI docs](https://pypi.org/help/#apitoken) for creating a token
-
-## Development Commands
-
-All commands are available via `make`:
-
-| Command | Description |
-|---------|-------------|
-| `make install` | Install all dependencies |
-| `make verify` | Run all checks (lint, format, type-check) |
-| `make fix` | Auto-fix lint and format issues |
-| `make test` | Run tests |
-| `make test-cov` | Run tests with coverage |
-| `make test-matrix` | Run tests across all Python versions |
-| `make test-matrix-cov` | Run tests with coverage across all versions |
-| `make docs` | Build documentation |
-| `make docs-serve` | Serve documentation locally |
-
-## Releasing a New Version
-
-1. Create a new version tag:
-
-   ```bash
-   git tag v0.1.0
-   git push --tags
-   ```
-
-2. The `release.yml` workflow will automatically:
-   - Build the distribution
-   - Publish to PyPI (if configured)
-   - Create a GitHub release with changelog
-
-## Generated Project Structure
-
-```
-my-project/
-├── src/
-│   └── my_project/
-│       ├── __init__.py
-│       ├── py.typed
-│       └── cli.py           # If CLI enabled
-├── tests/
-│   ├── __init__.py
-│   ├── conftest.py
-│   └── test_my_project.py
-├── docs/                     # If docs enabled
-│   ├── index.md
-│   ├── api.md
-│   └── contributing.md
-├── .github/
-│   └── workflows/           # If GitHub Actions enabled
-│       ├── ci.yml
-│       ├── release.yml
-│       └── docs.yml
-├── Makefile                 # Development commands
-├── pyproject.toml           # Single source of truth
-├── mkdocs.yml               # If docs enabled
-├── cliff.toml               # Changelog config
-├── .pre-commit-config.yaml  # If pre-commit enabled
-├── Dockerfile               # If Docker enabled
-├── .dockerignore            # If Docker enabled
-├── README.md
-├── CHANGELOG.md
-├── LICENSE
-└── .gitignore
-```
-
-## Updating Existing Projects
-
-Copier supports updating projects to newer template versions:
-
-```bash
-cd my-project
-copier update --trust
-```
+For the full user guide, template options, and contributing instructions, see the [documentation site](https://YOUR_USERNAME.github.io/copier-astral/).
 
 ## License
 

docs/contributing.md

@@ -0,0 +1,76 @@
+# Contributing
+
+## Development Setup
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/copier-astral.git
+cd copier-astral
+make install
+```
+
+## Running Tests
+
+The template includes a test suite that generates a project from the template and verifies it:
+
+```bash
+make test
+```
+
+To run linting and type checks:
+
+```bash
+make verify
+```
+
+Auto-fix lint and format issues:
+
+```bash
+make fix
+```
+
+## Building the Documentation
+
+```bash
+make docs-serve
+```
+
+This serves the docs locally at `http://127.0.0.1:8000/`.
+
+## Modifying the Template
+
+Template files live in the `template/` directory. Copier uses [Jinja2](https://jinja.palletsprojects.com/) for templating.
+
+Key files:
+
+- `copier.yml` — Template prompts and configuration
+- `extensions.py` — Custom Jinja2 extensions (slugify, git config, etc.)
+- `template/` — The generated project skeleton
+
+### Conditional files
+
+Files or directories can be conditionally included using Jinja2 expressions in the filename:
+
+```
+template/{% if include_docs %}mkdocs.yml{% endif %}.jinja
+template/{% if include_docker %}Dockerfile{% endif %}.jinja
+```
+
+### Testing your changes
+
+After modifying the template, run the test suite to make sure generated projects are still valid:
+
+```bash
+make test
+```
+
+You can also generate a test project manually:
+
+```bash
+copier copy --trust . /tmp/test-project
+cd /tmp/test-project
+make install
+make verify
+make test
+```