Skip to content

Commit 453be36

Browse files
thibaudcolasthibaudcolas
committed
Add first draft of docs overhaul
1 parent 77dc2f1 commit 453be36

18 files changed

+507
-377
lines changed

‎.travis.yml

-1
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@ jobs:
2525
- pip install poetry
2626
- poetry install
2727
script:
28-
- cp README.md docs/README.md
2928
- poetry run mkdocs build
3029
deploy:
3130
- provider: pages

‎CONTRIBUTING.md

+11
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,17 @@ npm run build
5353
npm run start
5454
```
5555

56+
### Documentation
57+
58+
The project’s documentation website is built with [MkDocs](https://www.mkdocs.org/).
59+
60+
```sh
61+
# One-off build.
62+
poetry run mkdocs build
63+
# Rebuild the docs as you work on them
64+
poetry run mkdocs serve
65+
```
66+
5667
## Running the tests
5768

5869
To run the python tests, use the script in the root of the repo:

‎README.md

+19-128
Original file line numberDiff line numberDiff line change
@@ -1,150 +1,41 @@
1-
# Django pattern library
1+
# [django-pattern-library](https://torchbox.github.io/django-pattern-library/)
22

33
[![PyPI](https://img.shields.io/pypi/v/django-pattern-library.svg)](https://pypi.org/project/django-pattern-library/) [![PyPI downloads](https://img.shields.io/pypi/dm/django-pattern-library.svg)](https://pypi.org/project/django-pattern-library/) [![Travis](https://travis-ci.com/torchbox/django-pattern-library.svg?branch=master)](https://travis-ci.com/torchbox/django-pattern-library) [![Total alerts](https://img.shields.io/lgtm/alerts/g/torchbox/django-pattern-library.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/torchbox/django-pattern-library/alerts/)
44

5-
A module for Django that helps you to build pattern libraries.
5+
> UI pattern libraries for Django templates
66
77
![Screenshot of the pattern library UI, with navigation, pattern rendering, and configuration](https://raw.githubusercontent.com/torchbox/django-pattern-library/master/.github/pattern-library-screenshot.webp)
88

9-
## Documentation
10-
11-
Documentation is located on GitHub in [`docs/`](https://github.com/torchbox/django-pattern-library/tree/master/docs).
12-
13-
## Objective
14-
15-
At the moment, the main focus is to allow developers and designers
16-
use exactly the same Django templates in a design pattern library
17-
and in production code.
18-
19-
There are a lot of alternative solutions for building
20-
pattern libraries already. Have a look at [Pattern Lab](http://patternlab.io/) and
21-
[Astrum](http://astrum.nodividestudio.com/), for example.
22-
But at [Torchbox](https://torchbox.com/) we mainly use Python and Django and
23-
we find it hard to maintain layout on big projects in several places:
24-
in a project's pattern library and in actual production code. This is our
25-
attempt to solve this issue and reduce the amount of copy-pasted code.
26-
27-
To learn more about how this package can be used, have a look at our Wagtail Space 2020 talk: [Reusable UI components: A journey from React to Wagtail](https://www.youtube.com/watch?v=isrOufI7TKc)
28-
29-
[![Reusable UI components: A journey from React to Wagtail](https://raw.githubusercontent.com/torchbox/django-pattern-library/master/.github/pattern-library-talk-youtube.webp)](https://www.youtube.com/watch?v=isrOufI7TKc)
30-
31-
## Concepts
32-
To understand how `django-pattern-library` works, the following concepts are important.
33-
34-
### Patterns
35-
Any template that is displayed by the pattern library is referred to as a pattern. Patterns are divided into two categories: fragments and pages.
36-
37-
### Fragments
38-
A fragment is a pattern whose markup does not include all of the resources (typically CSS and Javascript) for it to be displayed correctly on its own. This is typical for reusable component templates which depend on global stylesheets or Javascript bundles to render and behave correctly.
39-
40-
To enable them to be correctly displayed in the pattern library, `django-pattern-library` will inject the rendered markup of fragments into the **pattern base template** specified by `PATTERN_LIBRARY['PATTERN_BASE_TEMPLATE_NAME']`.
41-
42-
This template should include references to any required static files. The rendered markup of fragments will be available in the `pattern_library_rendered_pattern` context variable (see the tests for [an example](https://github.com/torchbox/django-pattern-library/blob/master/tests/templates/patterns/base.html)).
43-
44-
### Pages
45-
In contrast to fragments, pages are patterns that include everything they need to be displayed correctly in their markup. Pages are defined by `PATTERN_LIBRARY['BASE_TEMPLATE_NAMES']`.
46-
47-
Any template in that list — or that extends a template in that list — is considered a page and will be displayed as-is when rendered in the pattern library.
48-
49-
It is common practice for page templates to extend the pattern base template to avoid duplicate references to stylesheets and Javascript bundles. Again, [an example](https://github.com/torchbox/django-pattern-library/blob/master/tests/templates/patterns/base_page.html) of this can be seen in the tests.
9+
## Features
5010

51-
## How to install
11+
This package automates the maintenance of UI pattern libraries or styleguides for Django projects, and allows developers to experiment with Django templates without having to create Django views and models.
5212

53-
First install the library:
13+
- Create reusable patterns by creating Django templates files as usual.
14+
- All patterns automatically show up in the pattern library’s interface.
15+
- Define data as YAML files for the templates to render with the relevant Django context.
16+
- Override Django templates tags as needed to mock the template’s dependencies.
17+
- Document your patterns with Markdown.
5418

55-
```sh
56-
pip install django-pattern-library
57-
# ... or...
58-
poetry add django-pattern-library
59-
```
60-
61-
62-
Then, in your Django settings, add `pattern_library` into your `INSTALLED_APPS`, and `pattern_library.loader_tags` to `OPTIONS['builtins']` into the `TEMPLATES` setting. For example:
63-
64-
```python
65-
INSTALLED_APPS = [
66-
# ...
67-
'pattern_library',
68-
# ...
69-
]
70-
71-
TEMPLATES = [
72-
{
73-
'BACKEND': 'django.template.backends.django.DjangoTemplates',
74-
'DIRS': [],
75-
'APP_DIRS': True,
76-
'OPTIONS': {
77-
'context_processors': [
78-
'django.template.context_processors.debug',
79-
'django.template.context_processors.request',
80-
'django.contrib.auth.context_processors.auth',
81-
'django.contrib.messages.context_processors.messages',
82-
],
83-
'builtins': ['pattern_library.loader_tags'],
84-
},
85-
},
86-
]
87-
```
88-
89-
Note that this module only supports the Django template backend.
90-
91-
### Settings
92-
93-
Next, set the `PATTERN_LIBRARY` setting. Here's an example showing the defaults:
94-
95-
```python
96-
PATTERN_LIBRARY = {
97-
# PATTERN_BASE_TEMPLATE_NAME is the template that fragments will be wrapped with.
98-
# It should include any required CSS and JS and output
99-
# `pattern_library_rendered_pattern` from context.
100-
'PATTERN_BASE_TEMPLATE_NAME': 'patterns/base.html',
101-
# Any template in BASE_TEMPLATE_NAMES or any template that extends a template in
102-
# BASE_TEMPLATE_NAMES is a "page" and will be rendered as-is without being wrapped.
103-
'BASE_TEMPLATE_NAMES': ['patterns/base_page.html'],
104-
'TEMPLATE_SUFFIX': '.html',
105-
# SECTIONS controls the groups of templates that appear in the navigation. The keys
106-
# are the group titles and the values are lists of template name prefixes that will
107-
# be searched to populate the groups.
108-
'SECTIONS': (
109-
('atoms', ['patterns/atoms']),
110-
('molecules', ['patterns/molecules']),
111-
('organisms', ['patterns/organisms']),
112-
('templates', ['patterns/templates']),
113-
('pages', ['patterns/pages']),
114-
),
115-
}
116-
117-
```
118-
119-
Note that the templates in your `PATTERN_LIBRARY` settings must be available to your project's
120-
[template loaders](https://docs.djangoproject.com/en/3.1/ref/templates/api/#loader-types).
121-
122-
### URLs
123-
124-
Include `pattern_library.urls` in your `urlpatterns`. Here's an example `urls.py`:
19+
## Documentation
12520

126-
```python
127-
from django.apps import apps
128-
from django.conf.urls import url, include
21+
Documentation is available at [torchbox.github.io/django-pattern-library/](https://torchbox.github.io/django-pattern-library/), with source files in the `docs` directory.
12922

130-
urlpatterns = [
131-
# ... Your URLs
132-
]
23+
- [Getting started](https://torchbox.github.io/django-pattern-library/getting-started/)
24+
- Guides
25+
- Reference
13326

134-
if apps.is_installed('pattern_library'):
135-
urlpatterns += [
136-
url(r'^pattern-library/', include('pattern_library.urls')),
137-
]
138-
```
27+
## Examples of usage
13928

140-
This package is not intended for production. It is **highly recommended** to only enable this package in testing environments for a restricted, trusted audience. One simple way to do this is to only expose its URLs if `apps.is_installed('pattern_library')`, as demonstrated above, and only have the app installed in environment-specific settings.
29+
At [Torchbox](https://torchbox.com/), we use this package for all of the Wagtail websites we build, for example [rca.ac.uk](https://github.com/torchbox/rca-wagtail-2019).
14130

14231
## Contributing
14332

14433
See anything you like in here? Anything missing? We welcome all support, whether on bug reports, feature requests, code, design, reviews, tests, documentation, and more. Please have a look at our [contribution guidelines](https://github.com/torchbox/django-pattern-library/blob/master/CONTRIBUTING.md).
14534

146-
If you just want to set up the project on your own computer, the contribution guidelines also contain all of the setup commands.
35+
If you want to set up the project on your own computer, the contribution guidelines also contain all of the setup commands.
14736

14837
## Credits
14938

15039
View the full list of [contributors](https://github.com/torchbox/django-pattern-library/graphs/contributors). [BSD](https://github.com/torchbox/django-pattern-library/blob/master/LICENSE) licensed.
40+
41+
Project logo from [FxEmoji](https://github.com/mozilla/fxemoji). Documentation website built with [MkDocs](https://www.mkdocs.org/), and hosted in [GitHub Pages](https://pages.github.com/).

‎docs/README.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Documentation
2+
3+
This documentation is built as a website with [MkDocs](https://www.mkdocs.org/): [torchbox.github.io/django-pattern-library/](https://torchbox.github.io/django-pattern-library/).
4+
5+
To build locally, view the project’s `CONTRIBUTING.md`.

‎docs/getting-started.md

+170
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Getting started
2+
3+
## Installation
4+
5+
django-pattern-library is available [on PyPI](https://pypi.org/project/django-pattern-library/). First install it in your Django project:
6+
7+
```sh
8+
# With pip,
9+
pip install django-pattern-library
10+
# Alternatively, with Poetry,
11+
poetry add --dev django-pattern-library
12+
```
13+
14+
### Compatibility
15+
16+
We support:
17+
18+
- Django 2.2.x, 3.0.x, 3.1.x
19+
- Python 3.6, 3.7, 3.8
20+
- Django Templates only, no Jinja support
21+
22+
## Configuration
23+
24+
### Django settings
25+
26+
In your Django settings file, add `pattern_library` to `INSTALLED_APPS`:
27+
28+
```python
29+
INSTALLED_APPS = [
30+
# ...
31+
"pattern_library",
32+
# ...
33+
]
34+
```
35+
36+
Also add `pattern_library.loader_tags` to `OPTIONS["builtins"]` into the `TEMPLATES` setting:
37+
38+
```python
39+
TEMPLATES = [
40+
{
41+
"BACKEND": "django.template.backends.django.DjangoTemplates",
42+
"DIRS": [],
43+
"APP_DIRS": True,
44+
"OPTIONS": {
45+
"context_processors": [
46+
"django.template.context_processors.debug",
47+
"django.template.context_processors.request",
48+
"django.contrib.auth.context_processors.auth",
49+
"django.contrib.messages.context_processors.messages",
50+
],
51+
"builtins": [
52+
"pattern_library.loader_tags"
53+
],
54+
},
55+
},
56+
]
57+
```
58+
59+
### Pattern library settings
60+
61+
Still in Django settings, set the `PATTERN_LIBRARY` setting. Here is an example showing the defaults:
62+
63+
```python
64+
PATTERN_LIBRARY = {
65+
# Groups of templates for the pattern library navigation. The keys
66+
# are the group titles and the values are lists of template name prefixes that will
67+
# be searched to populate the groups.
68+
"SECTIONS": (
69+
("components", ["patterns/components"]),
70+
("pages", ["patterns/pages"]),
71+
),
72+
73+
# Configure which files to detect as templates.
74+
"TEMPLATE_SUFFIX": ".html",
75+
76+
# Set which template components should be rendered inside of,
77+
# so they may use page-level component dependencies like CSS.
78+
"PATTERN_BASE_TEMPLATE_NAME": "patterns/base.html",
79+
80+
# Any template in BASE_TEMPLATE_NAMES or any template that extends a template in
81+
# BASE_TEMPLATE_NAMES is a "page" and will be rendered as-is without being wrapped.
82+
"BASE_TEMPLATE_NAMES": ["patterns/base_page.html"],
83+
}
84+
```
85+
86+
Note the templates in your `PATTERN_LIBRARY` settings must be available to [template loaders](https://docs.djangoproject.com/en/3.1/ref/templates/api/#loader-types).
87+
88+
### URLs
89+
90+
Include `pattern_library.urls` in your `urlpatterns`. Here is an example `urls.py`:
91+
92+
```python
93+
from django.apps import apps
94+
from django.urls import include, path
95+
96+
urlpatterns = [
97+
# … Your URLs
98+
]
99+
100+
if apps.is_installed("pattern_library"):
101+
urlpatterns += [
102+
path("pattern-library/", include("pattern_library.urls")),
103+
]
104+
```
105+
106+
!!! warning "Security"
107+
108+
This package isn’t intended for production usage, and hasn’t received extensive security scrutiny.
109+
110+
It is **highly recommended** to only enable this package in testing environments, for a restricted, trusted audience. One way to do this is to only expose its URLs if `apps.is_installed("pattern_library")`, as demonstrated above, and only have the app installed in environment-specific settings.
111+
112+
---
113+
114+
Alright, now that we got this far, we can navigate to `http://localhost:8000/pattern-library/` to see our pattern library! But if we tried to do this now, we would likely get a `PatternLibraryEmpty` error – this is expected, as we haven’t added any patterns yet.
115+
116+
![Screenshot of the PatternLibraryEmpty error message from Django](images/getting-started/PatternLibraryEmpty.png)
117+
118+
Now let’s look at adding our first template!
119+
120+
## First pattern
121+
122+
Now we’ve done all of the configuration – let’s create a UI component. We’ll use `quote-block` as an example, and place it at `patterns/components/quote_block/quote_block.html` inside one of our Django apps:
123+
124+
```html
125+
<blockquote class="quote-block block--spacing">
126+
<div class="quote-block__text">
127+
<p class="quote-block__quote">{{ quote }}</p>
128+
{% if attribution %}
129+
<p class="quote-block__attribution">{{ attribution }}</p>
130+
{% endif %}
131+
</div>
132+
</blockquote>
133+
```
134+
135+
### Base template
136+
137+
We additionally need to customize a base template, so the standalone component can be rendered within a page with CSS. This is what the `PATTERN_BASE_TEMPLATE_NAME` setting is for. As a separate template in `patterns/base.html`:
138+
139+
```html
140+
<!DOCTYPE html>
141+
<html lang="en">
142+
<head>
143+
<meta charset="UTF-8">
144+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
145+
<title>My Base</title>
146+
</head>
147+
<body>
148+
{% block content %}
149+
{# pattern_library_rendered_pattern is where the pattern library will inject the rendered pattern. #}
150+
{{ pattern_library_rendered_pattern }}
151+
{% endblock %}
152+
</body>
153+
</html>
154+
```
155+
156+
`quote_block` should now appear in the pattern library UI menu! But the template doesn’t display anything – we additionally need to provide it with test data.
157+
158+
### Component data
159+
160+
We can provide context and tags overrides for our new component by creating a `quote_block.yaml` YAML file alongside the HTML, at `patterns/components/quote_block/quote_block.yaml` in our example.
161+
162+
```yaml
163+
context:
164+
quote: What is love?
165+
attribution: Haddaway
166+
```
167+
168+
And that’s it! Our `quote_block` should finally appear in the pattern library, along with its rendering with this mock data.
169+
170+
![Screenshot of the quote_block template](images/getting-started/getting-started-complete.png)

‎docs/guides/customizing-template-rendering.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Customizing template rendering
2+
3+
## Customizing the patterns’ surroundings
4+
5+
All patterns that are not pages are rendered within a base page template. The pattern library will render patterns inside the `content` block, which you can tweak to change how patterns are displayed.
6+
7+
You can for example add a theme wrapper around the components:
8+
9+
```html
10+
{% block content %}
11+
{% if pattern_library_rendered_pattern %}
12+
<div class="pattern-library bg bg--light">
13+
{{ pattern_library_rendered_pattern }}
14+
</div>
15+
{% endif %}
16+
{% endblock %}
17+
```
18+
19+
`pattern_library_rendered_pattern` can also be used to do other modifications on the page for the pattern library only, for example adding an extra class to `<body>`:
20+
21+
```html
22+
<body class="{% block body_class %}{% endblock %}{% if pattern_library_rendered_pattern %} pattern-library-template{% endif %}">
23+
```

0 commit comments

Comments
 (0)