Update dev instructions

Makefile

@@ -109,6 +109,11 @@ docs: ## Regenerate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs html
 
 
+.PHONY: serve
+serve: ## Serve docs at http://localhost:8000
+	python -m http.server --directory ./docs/_build/html
+
+
 .PHONY: frontend
 frontend: ## Compile frontend files
 	npm run frontend

README.md

@@ -39,8 +39,13 @@ html_theme = 'sphinx_wagtail_theme'
 -   Clone this repo locally
 -   Set up a Python virtual environment (e.g. `venv`)
 -   Show all available tasks via `make`
--   Run `make setup` and then `make docs` to install and build the docs locally
--   See the documentation for more development instructions
+-   Run `make setup` to install the dependencies
+-   Run `make frontend` to build the frontend assets
+-   Run `make install-for-dev` to build the theme package and install it in editable mode
+-   Run `make docs` to build the theme docs, which also serve as the example docs to develop the theme
+-   Run `make serve` to serve the theme docs at http://localhost:8000
+
+See the documentation for more development instructions.
 
 ### Release process
 

docs/development.rst

@@ -29,13 +29,13 @@ Build and install the package::
 
    make install
 
-Don't forget to update the docs. Render the documentation and show in browser::
+Don't forget to update the docs. Render the documentation::
 
    make docs
 
-Without opening the browser::
+Serve build docs locally::
 
-   non_interactive=1 make docs
+   make serve
 
 Check the Python code. The CI workflow requires `lint-minimal` to succeed::
 
@@ -66,19 +66,13 @@ can be uploaded to PyPi run::
 .. _venv: https://docs.python.org/3/library/venv.html
 
 
-Theme stress test
-=================
+Example pages
+=============
 
-There is a demo manual `t3SphinxThemeRtdDemoDocs`_
-under construction. It serves as a "stress test" for this `sphinx_wagtail_theme`_
-and tries to use as many reStructuredText examples as possible and covered by
-the theme. **Documentation writers** may want to have a look at those pages to
-understand what reST markup can be used and what the visual effect will be.
-**Theme contributors** should use the demo manual for testing and *visually*
-check the rendering.
+When working on the theme it is often going to be helpful to know the impact of your changes.
+The :doc:`examples section <examples/index>` should be helpful for this.
 
-.. _t3SphinxThemeRtdDemoDocs: https://docs.typo3.org/m/typo3/demo-t3SphinxThemeRtd/master/en-us/
-.. _sphinx_wagtail_theme: https://github.com/typo3-documentation/sphinx_wagtail_theme
+When you are adding new elements or styles that are not part of the examples, please make sure to add them.
 
 
 Javascript package management