Created a tutorial, made some changes to the home page

docs/source/index.rst

@@ -1,7 +1,34 @@
-Welcome to Neapolitan's documentation!
+Neapolitan
 ======================================
 
-Neapolitan provides quick CRUD views for Django.
+Neapolitan is a re-usable library for Django projects, that provides quick CRUD views
+for other applications.
+
+It helps you get your models into your web output as quickly as possible, and includes base
+templates and re-usable template tags.
+
+All kinds of applications need frontend CRUD functionality - but it's not available out of
+the box with Django, and Python programmers often suffer while wrestling with the unfamiliar
+technologies and tools required to implement it. Neapolitan addresses that particular
+headache.
+
+If you've ever looked longingly at Django's admin functionality and wished you could have
+the same kind of CRUD access that it provides for your frontend, then Neapolitan is for you.
+
+
+Contents
+--------
+
+.. toctree::
+    :maxdepth: 1
+
+    tutorial
+    crud-view
+    templates
+
+
+A quick look
+------------
 
 I have a Django model::
 
@@ -24,34 +51,21 @@ I want easy CRUD views for it, without it taking all day::
 
     urlpatterns = [ ... ] + BookmarkView.get_urls()
 
-Neapolitan's ``CRUDView`` provides the standard list, detail,
-create, edit, and delete views for a model, as well as the hooks you need to
-be able to customise any part of that.
-
-Neapolitan provides base templates and re-usable template tags to make getting
-your model on the page as easy as possible.
+Read the :ref:`tutorial` for a step-by-step guide to getting it up and running. Let's go! 🚀
 
-Where you take your app after that is up to you. But Neapolitan will get you
-started.
 
-Let's go! 🚀
+Contribute!
+-----------
 
+Neapolitan is very much under construction 🚧.
 
-.. toctree::
-    :maxdepth: 1
-    :caption: Contents:
+The docs are still fledging. **But** you can read
+``neapolitan.views.CRUDView`` to see what it does. (It's just the one
+class!)
 
-    crud-view
-    templates
+Whilst I'm working on it, if you wanted to make a PR adding a docstring and
+an ``.. automethod::``… you'd be welcome to do so! 🎁
 
-.. admonition:: Under construction 🚧
-
-    The docs are still fledging. **But** you can read
-    ``neapolitan.views.CRUDView`` to see what it does. (It's just the one
-    class!)
-
-    Whilst I'm working on it, if you wanted to make a PR adding a docstring and
-    an ``.. automethod::``… you'd be welcome to do so! 🎁
 
 What about the name?
 --------------------
@@ -62,12 +76,3 @@ the way to sanity in regards to class-based views. 🥰 I needed just a little b
 more — filtering, generic templates, auto-routing of multiple views, and that's
 about it really — but what's that little bit more than Vanilla?
 `Neapolitan <https://en.wikipedia.org/wiki/Neapolitan_ice_cream>`_! 🍨
-
-
-..
-   Indices and tables
-   ==================
-
-   * :ref:`genindex`
-   * :ref:`modindex`
-   * :ref:`search`

docs/source/templates.rst

@@ -1,5 +1,5 @@
 ======================
-Neapolitan's Templates
+Template reference
 ======================
 
 Neapolitan provides generic templates that can be used as a starting point for

docs/source/tutorial.rst

@@ -0,0 +1,88 @@
+.. _tutorial:
+
+Tutorial
+=========
+
+This tutorial will walk you through an example that introduces key operations and
+concepts in Neapolitan. It assumes basic familiarity with Django.
+
+The tutorial will build a dashboard for a set of software projects.
+
+Prepare a new Django project
+----------------------------
+
+With Django installed, start a new Django project (in a virtual environment, preferably)::
+
+    django-admin startproject dashboard
+
+In the new project directory, create a ``projects`` application::
+
+    python manage.py startapp projects
+
+In ``projects/models.py``, define a ``Project``::
+
+    class Project(models.Model):
+        name = models.CharField(max_length=200)
+        has_tests = models.BooleanField()
+        has_docs = models.BooleanField()
+
+and add the project, the ``projects`` module and Neapolitan to the beginning of
+ ``INSTALLED_APPS`` in ``settings.py``::
+
+    INSTALLED_APPS = [
+        'projects',
+        'neapolitan',
+        'dashboard',
+        [...]
+    ]
+
+Create migrations, and run them::
+
+    python manage.py makemigrations
+    python manage.py migrate
+
+Wire up the admin; in ``projects/admin.py``::
+
+    from .models import Project
+
+    admin.site.register(Project)
+
+and create a superuser::
+
+    python manage.py createsuperuser
+
+Finally, start the runserver and in the admin, add a few ``Project`` objects to the database.
+
+
+Wire up Neapolitan views
+------------------------
+
+Neapolitan expects to extend a base template (its own templates use
+``{% extends "base.html" %}`` so you'll have to provide one at ``dashboard/templates/
+base.html``::
+
+    {% block content %}{% endblock %}
+
+
+And at the end of ``dashboard/urls.py``::
+
+    from neapolitan.views import CRUDView
+
+    import projects
+
+    class ProjectView(CRUDView):
+        model = projects.models.Project
+        fields = ["name", "has_tests", "has_docs"]
+
+    urlpatterns += ProjectView.get_urls()
+
+At this point, you can see Neapolitan in action at ``/project/`` (e.g.
+http://127.0.0.1:8000/project/). It won't look very beautiful, but you'll see
+a table of objects and their attributes, along with options to change their values.
+
+
+Next steps
+----------
+
+The default templates use TailwindCSS classes, for styling. You will need to `integrate TailwindCSS into Django
+<https://noumenal.es/notes/tailwind/django-integration/>`_.