Add documentation for render_patterns

Author: thibaudcolas

CONTRIBUTING.md

@@ -64,7 +64,7 @@ The project’s documentation website is built with [MkDocs](https://www.mkdocs.
 # One-off build.
 poetry run mkdocs build --strict
 # Rebuild the docs as you work on them
-poetry run mkdocs serve --strict
+poetry run mkdocs serve
 ```
 
 ## Running the tests

README.md

@@ -36,7 +36,7 @@ Documentation is available at [torchbox.github.io/django-pattern-library](https:
   - [Defining template context](https://torchbox.github.io/django-pattern-library/guides/defining-template-context/)
   - [Overriding template tags](https://torchbox.github.io/django-pattern-library/guides/overriding-template-tags/)
   - [Customizing template rendering](https://torchbox.github.io/django-pattern-library/guides/customizing-template-rendering/)
-  - [Workflows that work](https://torchbox.github.io/django-pattern-library/guides/workflows-that-work/)
+  - [Usage tips](https://torchbox.github.io/django-pattern-library/guides/usage-tips/)
 - **Reference**
   - [API & settings](https://torchbox.github.io/django-pattern-library/reference/api/)
   - [Known issues and limitations](https://torchbox.github.io/django-pattern-library/reference/known-issues/)

docs/guides/automated-tests.md

@@ -0,0 +1,35 @@
+# Automated tests
+
+Although pattern libraries often start as tools for manual tests during development, they can also be useful for automated UI testing. There are a few benefits to doing UI tests with a pattern library:
+
+- Test the components in isolation. When tests fail, you will know exactly which component has issues, rather than having to inspect whole pages to understand what might have changed.
+- Test the components with mock data. One of the issues with UI tests is to have test data for your UIs to render – you can reuse the pattern library data for this purpose (althoug there are [limitations](../guides/multiple-variants.md)).
+
+## Setting up automated UI tests
+
+There are two ways to set up automated tests: by accessing templates as they are rendered by the pattern library directly with Django, or by pre-rendering the templates with [`render_patterns` command](../reference/api.md#render_patterns) and then using this static export to make automated tests.
+
+### Served by Django
+
+Make sure your Django server is up and running, and you can then point your tests directly at the pattern library’s iframe URLs, for example: `http://localhost:8000/pattern-library/render-pattern/patterns/molecules/accordion/accordion.html`.
+
+Note this will always render your templates within the base template ([`PATTERN_BASE_TEMPLATE_NAME`](../reference/api.md#pattern_base_template_name)), which may or may not be appropriate for your tests.
+
+### With `render_patterns`
+
+The [`render_patterns` command](../reference/api.md#render_patterns) command can be used to export all your templates, so you can do bulk checks on them all. For example, testing all templates use valid HTML with the [v.Nu HTML5 validator](https://validator.github.io/validator/):
+
+```sh
+./manage.py render_patterns --wrap-fragments
+vnu dpl-rendered-patterns/**/*.html
+```
+
+One of the advantages of `render_patterns` is the ability for you to test the patterns without wrapping fragments in the base template, should this be more appropriate for your tests.
+
+## Visual regression testing
+
+Pattern libraries are a natural fit for automated visual regression tests. Check out [BackstopJS](https://github.com/garris/BackstopJS) to get started.
+
+## Accessibility testing
+
+Here as well, pattern libraries are a natural fit, due to them providing the test data, and making it possible to test components in isolation. Have a look at [Pa11y](https://pa11y.org/) or [Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci) to get started.

docs/guides/static-site-export.md

@@ -0,0 +1,45 @@
+# Static site export
+
+It can be useful to publish your pattern library as a static site – for example to host it without a runtime dependency on the rest of your code, or to save past versions, or save the output as build artifacts.
+
+## With `render_patterns`
+
+The [`render_patterns` command](../reference/api.md#render_patterns) command can be used to export all your templates, without exporting the pattern library UI.
+
+```sh
+# Export all templates, wrapped in the base template like the pattern library UI does.
+./manage.py render_patterns --wrap-fragments --output dpl-rendered-patterns
+# Or alternatively export all templates without extra wrapping.
+./manage.py render_patterns --output dpl-rendered-patterns
+```
+
+This command will create a new folder, with a structure matching that of your templates:
+
+```txt
+dpl-rendered-patterns
+├── atoms
+│   ├── icons
+│   │   └── icon.html
+├── molecules
+│   ├── accordion
+│   │   └── accordion.html
+└── pages
+    └── people
+        └── person_page.html
+```
+
+Note this will export all templates but won’t export static files. If you need static files for your export, additionally run [`collectstatic`](https://docs.djangoproject.com/en/3.1/ref/contrib/staticfiles/#collectstatic), and move its output to be where [`STATIC_URL`](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-STATIC_URL) expects it:
+
+```sh
+./manage.py collectstatic
+# Moving the collected files to match STATIC_URL
+mv static dpl-rendered-patterns/static
+```
+
+## With a website scrapper
+
+It’s very straightforward to export the whole pattern library as a static site, including all templates, and the pattern library UI. Here is an example exporting the pattern library with [`wget`](https://en.wikipedia.org/wiki/Wget):
+
+```sh
+wget --mirror --page-requisites --no-parent http://localhost:8000/pattern-library
+```

docs/guides/usage-tips.md

@@ -0,0 +1,54 @@
+# Usage tips
+
+The workflow of developing UI components in a pattern library can be quite different from one-off templates that are only rendered where they are used. Here are tips to make the most of it.
+
+## Keep the pattern library in sync
+
+One of the upsides of having the pattern library built with Django is that the HTML templates can never go out of sync – but the data can! Make sure your template context and tag overrides keep in sync with your actual templates. This can for example be part of a code review checklist.
+
+You may also consider using the [`render_patterns` command](../reference/api.md#render_patterns) to have a baseline check the patterns don’t raise errors while rendering.
+
+## Document your patterns
+
+Patterns support defining a custom `name` in YAML, as well as rendering fully-fledged documentation in Markdown. Create a file next to the template to document it:
+
+```markdown
+This template can be used in different places. In streamfield block
+or directly in a page template. To use this template pass `call_to_action` into context.
+
+Example:
+
+{% include "patterns/molecules/cta/call_to_action.html" with call_to_action=call_to_action %}
+```
+
+## Test faster
+
+One of the main points of maintaining a pattern library is to be able to work on UI components in isolation from where they are used, which is very useful when testing components – access them directly in the pattern library, rather than always having to figure out where they are used, and manually navigating to them.
+
+You can use the pattern library’s iframe view directly to test the component without the pattern library UI, but remember that the pattern will be displayed wrapped in the base template ([`PATTERN_BASE_TEMPLATE_NAME`](../reference/api.md#pattern_base_template_name)), which isn’t always truthful to how components are used in situ.
+
+A pattern library can also help with [automated tests](../guides/automated-tests.md).
+
+## Iterate on components
+
+### Back-end first
+
+Traditionally, Django development starts from models, and everything else is derived from the models’ structure. This is very natural from a back-end perspective – first define your data model, then the view(s) that reuse it, and finally templates.
+
+We generally recommend this approach, but keep in mind that:
+
+- With this workflow it’s natural to write templates that are heavily tied to the database structure, and as such not very reusable, and may be out of touch with visual design.
+- There can be work needed later on to reconcile the data structure as defined by the back-end, with what is mandated by the designs.
+
+To mitigate this risk, and overall make templates more reusable, take the time to massage data into basic structures that map better to visual representations.
+
+### Front-end first
+
+Alternatively, the pattern library makes it possible to write templates without models and views. This can be very convenient if your project’s schedule requires this kind of progression.
+
+With this approach, keep in mind that:
+
+- When creating the template from UI principles, there will be assumptions made about the underlying data structures to be provided by Django models. Templates will be heavily tied to their visual design (which generally uses basic data structures like lists and mappings), and may be out of touch with the models once they are created.
+- There will be work to do to reconcile the data structure as defined in the UI components, with what is mandated by the models.
+
+Here as well, to mitigate this risk, and overall make templates more reusable, take the time to massage data into basic structures that map better to visual representations.

docs/guides/workflows-that-work.md

@@ -116,3 +116,27 @@ PATTERN_LIBRARY = {
     "BASE_TEMPLATE_NAMES": ["patterns/base_page.html"],
 }
 ```
+
+## Commands
+
+### `render_patterns`
+
+Renders all django-pattern-library patterns to HTML files, in a directory
+structure. This can be useful for [automated tests](../guides/automated-tests.md)
+
+Usage:
+
+```sh
+# Render all patterns to the default directory.
+./manage.py render_patterns
+# Render patterns without outputting files.
+./manage.py render_patterns --dry-run
+# Render all patterns, with fragment patterns wrapped in the base template.
+./manage.py render_patterns --wrap-fragments
+# Render patterns to a specific directory.
+./manage.py render_patterns --output ./my/path/relative/to/cwd
+# Render patterns to stdout.
+./manage.py render_patterns --dry-run --verbosity 2
+# View all options
+./manage.py render_patterns --help
+```

docs/reference/api.md

@@ -33,10 +33,12 @@ nav:
   # The most important guides are shown in the top-level navigation.
   - 'Template context': 'guides/defining-template-context.md'
   - 'Overriding tags': 'guides/overriding-template-tags.md'
-  - 'Workflows that work': 'guides/workflows-that-work.md'
+  - 'Usage tips': 'guides/usage-tips.md'
   - 'Guides':
     - 'Customizing rendering': 'guides/customizing-template-rendering.md'
     - 'Multiple variants': 'guides/multiple-variants.md'
+    - 'Automated tests': 'guides/automated-tests.md'
+    - 'Static site export': 'guides/static-site-export.md'
     - 'Reuse across projects': 'guides/reuse-across-projects.md'
   - 'Recipes':
     - 'Inclusion tags': 'recipes/inclusion-tags.md'

mkdocs.yml

@@ -1,5 +1,5 @@
 <svg style="display: none;">
-    <symbol id="close" width="24" height="24" viewBox="0 0 24 24">
+    <symbol id="close" viewBox="0 0 24 24">
         <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"></path>
         <path d="M0 0h24v24H0z" fill="none"></path>
     </symbol>