Skip to content

Commit 90061a8

Browse files
matagusmatagus
committed
Docs published to Github Pages using gh action
1 parent 87169b1 commit 90061a8

File tree

8 files changed

+273
-0
lines changed

8 files changed

+273
-0
lines changed

‎.github/workflows/gh-pages.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Publish docs via GitHub Pages
2+
on:
3+
workflow_dispatch:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
build:
10+
name: Deploy docs
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout main
14+
uses: actions/checkout@v5
15+
16+
- name: Set up Python
17+
uses: actions/setup-python@v5
18+
with:
19+
python-version: '3.12'
20+
21+
- name: Install dependencies
22+
run: |
23+
python -m pip install --upgrade pip
24+
pip install .[docs]
25+
26+
- name: Build MkDocs
27+
run: mkdocs build
28+
29+
- name: Deploy to GitHub Pages
30+
uses: peaceiris/actions-gh-pages@v4
31+
with:
32+
github_token: ${{ secrets.GITHUB_TOKEN }}
33+
publish_dir: ./site

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,6 @@ data/
9191
# Build files
9292
dist/
9393
build/
94+
95+
# mkdocs
96+
site/

‎docs/contributing.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Contributing to django-admin-contexts
2+
3+
Thank you for considering contributing! ❤️
4+
5+
## Getting Started
6+
7+
**Prerequisites:** Python 3.9+ and [Hatch](https://hatch.pypa.io/)
8+
9+
```bash
10+
# Clone the repository
11+
git clone https://github.com/matagus/django-admin-contexts.git
12+
cd django-admin-contexts
13+
14+
# Install Hatch
15+
pip install hatch
16+
17+
# Install pre-commit hooks
18+
pip install pre-commit
19+
pre-commit install
20+
```
21+
22+
## Development Workflow
23+
24+
### Running the Example Project
25+
26+
```bash
27+
hatch run project:migrate
28+
hatch run project:createsuperuser
29+
hatch run project:runserver
30+
```
31+
32+
Visit http://127.0.0.1:8000/admin/ to test the app with a populated admin.
33+
34+
### Running Tests
35+
36+
```bash
37+
# All Python + Django combinations
38+
hatch run test:test
39+
40+
# Specific version
41+
hatch run test.py3.12-5.2:test
42+
43+
# With coverage
44+
hatch run test:cov
45+
```
46+
47+
### Code Style
48+
49+
We use Ruff and Black. Pre-commit hooks will automatically format your code.
50+
51+
```bash
52+
# Install pre-commit
53+
pip install pre-commit
54+
55+
# Set up git hooks
56+
pre-commit install
57+
58+
# Run hooks manually on all files
59+
pre-commit run --all-files
60+
```
61+
62+
## Pull Request Guidelines
63+
64+
1. **Fork and branch**: Create a feature branch from `main`
65+
2. **Write tests**: Add tests for new features or bug fixes
66+
3. **Update docs**: Update README.md if adding features
67+
4. **Keep it focused**: One feature/fix per PR
68+
5. **Test thoroughly**: Ensure tests pass for all Python/Django versions
69+
70+
## Useful Links
71+
72+
- **Repository**: https://github.com/matagus/django-admin-contexts
73+
- **Issues**: https://github.com/matagus/django-admin-contexts/issues
74+
- **Discussions**: https://github.com/matagus/django-admin-contexts/discussions
75+
76+
## Questions?
77+
78+
Open an issue for discussion before starting major changes. We're here to help!

‎docs/index.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Getting started with django-admin-contexts
2+
3+
![Python Compatibility](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)
4+
![Django Compatibility](https://img.shields.io/badge/django-4.2%20|%205.0%20|%205.1%20|%205.2-%2344B78B?labelColor=%23092E20)
5+
[![PyPi Version](https://img.shields.io/pypi/v/django-admin-contexts.svg)](https://pypi.python.org/pypi/django-admin-contexts)
6+
![CI badge](https://github.com/matagus/django-admin-contexts/actions/workflows/ci.yml/badge.svg)
7+
[![codecov](https://codecov.io/gh/matagus/django-admin-contexts/graph/badge.svg?token=a64SxEDQk0)](https://codecov.io/gh/matagus/django-admin-contexts)
8+
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
9+
10+
Display only a set of apps and models in the Django Admin homepage, based on the chosen context. This is useful when
11+
you have a lot of apps and models and you want to focus on a specific set of them.
12+
13+
![Demo: selecting a context to display only a subset of models](https://raw.githubusercontent.com/matagus/django-admin-contexts/main/screenshots/demo.gif)
14+
15+
## Installation
16+
17+
Via `pip` command:
18+
19+
```bash
20+
pip install django-admin-contexts
21+
```
22+
23+
...or you can clone the repo and install it using `pip` too:
24+
25+
```bash
26+
git clone git://github.com/matagus/django-admin-contexts.git
27+
cd django-admin-contexts
28+
pip install -e .
29+
```
30+
31+
## Quick Start
32+
33+
Add `django_admin_contexts` to your `INSTALLED_APPS` in `settings.py` **before** `django.contrib.admin`:
34+
35+
```python
36+
INSTALLED_APPS = (
37+
# ...
38+
"django_admin_contexts",
39+
# ...
40+
"django.contrib.admin",
41+
# ...
42+
)
43+
```
44+
45+
Then run the migrations:
46+
47+
```bash
48+
python manage.py migrate
49+
```
50+
51+
## Usage
52+
53+
Browse to the Django Admin and create some contexts in the "Django Admin Contexts" section, associating them with one
54+
or more models.
55+
56+
Then, you can see the contexts in the Django Admin homepage.
57+
58+
## Running Tests
59+
60+
**Prerequisites:** Install Hatch if not already installed: `pip install hatch`
61+
62+
**List available test environments:**
63+
```bash
64+
hatch env show test
65+
```
66+
67+
**Run all tests (all Python + Django combinations):**
68+
```bash
69+
hatch run test:test
70+
```
71+
72+
**Run tests for specific Python/Django version:**
73+
```bash
74+
hatch run test.py3.14-5.2:test # Python 3.14 + Django 5.2
75+
hatch run test.py3.12-5.1:test # Python 3.12 + Django 5.1
76+
```
77+
78+
**Run specific test file:**
79+
```bash
80+
hatch run test.py3.12-5.2:test tests.test_models
81+
```
82+
83+
**Coverage:**
84+
```bash
85+
hatch run test:cov # Run tests with coverage report
86+
```
87+
88+
**Troubleshooting:** If you encounter environment issues, clean and rebuild: `hatch env prune`

‎docs/license.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# License
2+
3+
## MIT License
4+
5+
Copyright (c) 2024-present, Matias Agustin Mendez and django-admin-contexts contributors
6+
7+
Permission is hereby granted, free of charge, to any person obtaining a copy
8+
of this software and associated documentation files (the "Software"), to deal
9+
in the Software without restriction, including without limitation the rights
10+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11+
copies of the Software, and to permit persons to whom the Software is
12+
furnished to do so, subject to the following conditions:
13+
14+
The above copyright notice and this permission notice shall be included in
15+
all copies or substantial portions of the Software.
16+
17+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23+
THE SOFTWARE.

‎mkdocs.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
site_name: django-admin-contexts
2+
site_url: https://github.com/matagus/django-admin-contexts
3+
repo_url: https://github.com/matagus/django-admin-contexts
4+
theme:
5+
name: "material"
6+
palette:
7+
primary: blue
8+
features:
9+
- navigation.instant
10+
- navigation.instant.prefetch
11+
- navigation.path
12+
- navigation.expand
13+
- navigation.tabs
14+
- navigation.tabs.sticky
15+
- toc.follow
16+
- tables
17+
nav:
18+
- Home: index.md
19+
- Contributing: contributing.md
20+
- License: license.md
21+
markdown_extensions:
22+
- toc:
23+
permalink: true
24+
- pymdownx.highlight:
25+
anchor_linenums: true
26+
line_spans: __span
27+
pygments_lang_class: true
28+
- pymdownx.inlinehilite
29+
- pymdownx.snippets
30+
- pymdownx.superfences

‎pyproject.toml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,12 @@ dependencies = ["Django>=4.2"]
3838

3939
[project.optional-dependencies]
4040
dev = ["ipython", "django-extensions", "Werkzeug", "django-debug-toolbar"]
41+
docs = [
42+
"mkdocs",
43+
"mkdocs-material",
44+
"pygments",
45+
"pymdown-extensions",
46+
]
4147

4248
[project.urls]
4349
Homepage = "https://github.com/matagus/django-admin-contexts"
@@ -59,6 +65,14 @@ include = ["django_admin_contexts/"]
5965
[tool.hatch.envs.default]
6066
features = ["dev"]
6167

68+
[tool.hatch.envs.docs]
69+
dependencies = ["mkdocs", "mkdocs-material", "pygments", "pymdown-extensions"]
70+
71+
[tool.hatch.envs.docs.scripts]
72+
new = "mkdocs new ."
73+
build = "mkdocs build {args}"
74+
serve = "mkdocs serve {args}"
75+
6276
[tool.hatch.envs.project]
6377
template = "default"
6478
extra-dependencies = [

‎requirements.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
mkdocs
2+
mkdocs-material
3+
pygments
4+
pymdown-extensions

0 commit comments

Comments
 (0)