Completely redo the documentation

Author: matthiask

CHANGELOG.rst

@@ -9,6 +9,8 @@ Next version
   admin enhancements (currently save shortcuts). The ``ContentEditor`` now
   inherits from this base class, and ``RefinedModelAdmin`` can be used
   independently for regular model admins that want these tweaks.
+- Reorganized the documentation and modified the quickstart section to no
+  longer mention or recommend CKEditor 4.
 
 
 7.3 (2025-06-23)

docs/admin-classes.rst

@@ -0,0 +1,111 @@
+=============
+Admin Classes
+=============
+
+ContentEditor
+=============
+
+The ``ContentEditor`` class extends ``RefinedModelAdmin`` and provides the full
+content editing interface for managing heterogeneous collections of content blocks.
+
+It automatically handles:
+
+- Plugin management and ordering
+- Region-based content organization
+- Drag-and-drop reordering of content blocks
+- Integration with ``ContentEditorInline`` classes
+
+Basic usage:
+
+.. code-block:: python
+
+    from content_editor.admin import ContentEditor, ContentEditorInline
+    from .models import Article, RichText, Download
+
+    @admin.register(Article)
+    class ArticleAdmin(ContentEditor):
+        inlines = [
+            ContentEditorInline.create(model=RichText),
+            ContentEditorInline.create(model=Download),
+        ]
+
+ContentEditorInline
+===================
+
+``ContentEditorInline`` is a specialized ``StackedInline`` that serves as a marker
+for content editor plugins. It provides additional functionality for:
+
+- Region restrictions
+- Custom icons and buttons
+- Plugin-specific configuration
+
+The ``.create()`` class method provides a convenient way to quickly create inlines:
+
+.. code-block:: python
+
+    ContentEditorInline.create(
+        model=MyPlugin,
+        icon="description",  # Material icon name
+        color="#ff5722",     # Custom color
+        regions={"main"},    # Restrict to specific regions
+    )
+
+Restricting plugins to regions
+------------------------------
+
+You may want to allow certain content blocks only in specific regions. For example,
+you may want to allow rich text content blocks only in the ``main`` region. There
+are several ways to do this; you can either hardcode the list of allowed regions:
+
+.. code-block:: python
+
+    from content_editor.admin import ContentEditor, allow_regions
+
+    class ArticleAdmin(ContentEditor):
+        inlines = [
+            # Explicit:
+            RichTextInline.create(regions={"main"}),
+            # Using the helper which does exactly the same:
+            RichTextInline.create(regions=allow_regions({"main"})),
+        ]
+
+Or you may want to specify a list of denied regions. This may be less
+repetitive if you have many regions and many restrictions:
+
+.. code-block:: python
+
+    from content_editor.admin import ContentEditor, deny_regions
+
+    class ArticleAdmin(ContentEditor):
+        inlines = [
+            RichTextInline.create(regions=deny_regions({"sidebar"})),
+        ]
+
+RefinedModelAdmin
+=================
+
+The ``RefinedModelAdmin`` class provides a lightweight base class that extends
+Django's ``ModelAdmin`` with commonly useful tweaks. It serves as the foundation
+for the ``ContentEditor`` class, but can also be used independently for regular
+Django admin classes that want to benefit from these enhancements.
+
+Currently, ``RefinedModelAdmin`` includes:
+
+- **Save shortcuts**: Keyboard shortcuts (Ctrl+S / Cmd+S) for quickly saving forms
+- **Deletion safety check**: Shows a confirmation dialog when attempting to delete
+  the whole object instead of saving changes (including marked inline deletions)
+
+To use ``RefinedModelAdmin`` for your own admin classes:
+
+.. code-block:: python
+
+    from content_editor.admin import RefinedModelAdmin
+
+    @admin.register(MyModel)
+    class MyModelAdmin(RefinedModelAdmin):
+        # Your admin configuration here
+        pass
+
+This gives you the save shortcut functionality without the full content editor
+interface, making it useful for any Django model admin where you want these
+convenience features.

docs/changelog.rst

@@ -0,0 +1,5 @@
+=========
+Changelog
+=========
+
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -1,3 +1,4 @@
+import datetime
 import os
 import re
 import subprocess
@@ -8,7 +9,7 @@
 
 project = "django-content-editor"
 author = "Feinheit AG"
-copyright = "2016-2017," + author  # noqa: A001
+copyright = f"2009-{datetime.date.today().year}, {author}"
 version = __import__("content_editor").__version__
 release = subprocess.check_output(
     "git fetch --tags; git describe", shell=True, text=True
@@ -30,8 +31,17 @@
 pygments_style = "sphinx"
 todo_include_todos = False
 
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
+
+# Theme options
+html_theme_options = {
+    "navigation_depth": 3,
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "includehidden": True,
+    "titles_only": False,
+}
 htmlhelp_basename = project_slug + "doc"
 
 latex_elements = {

docs/contents.rst

@@ -0,0 +1,147 @@
+=====================
+Contents and Regions
+=====================
+
+Regions
+=======
+
+The included ``Contents`` class and its helpers (``contents_*``) and
+the ``ContentEditor`` admin class expect a ``regions`` attribute or
+property (**not** a method) on their model which returns a list of ``Region`` instances.
+
+Regions have the following attributes:
+
+* ``title``: Something nice, will be visible in the content editor.
+* ``key``: The region key, used in the content proxy as attribute name
+  for the list of plugins. Must contain a valid Python identifier.
+  ``"regions"`` and names starting with an underscore cannot be used. The
+  recommendation is to use ``"main"`` when you only have a single region and no
+  better idea.
+* ``inherited``: Only has an effect if you are using the
+  ``inherit_from`` argument to ``contents_for_item``: Model instances
+  inherit content from their other instances if a region with
+  ``inherited = True`` is empty.
+
+You are free to define additional attributes -- simply pass them
+when instantiating a new region.
+
+Example:
+
+.. code-block:: python
+
+    from content_editor.models import Region
+
+    class Article(models.Model):
+        title = models.CharField(max_length=200)
+
+        regions = [
+            Region(key="main", title="Main content"),
+            Region(key="sidebar", title="Sidebar", inherited=True),
+        ]
+
+Contents class and helpers
+==========================
+
+The ``content_editor.contents`` module offers a few helpers for
+fetching content blocks from the database. The ``Contents`` class
+knows how to group content blocks by region and how to merge
+contents from several main models. This is especially useful in
+inheritance scenarios, for example when a page in a hierarchical
+page tree inherits some aside-content from its ancestors.
+
+.. note::
+
+   **Historical note**
+
+   The ``Contents`` class and the helpers replace the monolithic
+   ``ContentProxy`` concept in FeinCMS_.
+
+Contents class
+--------------
+
+Simple usage is as follows:
+
+.. code-block:: python
+
+    from content_editor.contents import Contents
+
+    article = Article.objects.get(...)
+    c = Contents(article.regions)
+    for item in article.app_richtext_set.all():
+        c.add(item)
+    for item in article.app_download_set.all():
+        c.add(item)
+
+    # Returns a list of all items, sorted by the definition
+    # order of article.regions and by item ordering
+    list(c)
+
+    # Returns a list of all items from the given region
+    c["main"]
+    # or
+    c.main
+
+    # How many items do I have?
+    len(c)
+
+    # Inherit content from the given contents instance if one of my
+    # own regions is empty and has its "inherited" flag set.
+    c.inherit_regions(some_other_contents_instance)
+
+    # Plugins from unknown regions end up in _unknown_region_contents:
+    c._unknown_region_contents
+
+For most use cases you'll probably want to take a closer look at the
+following helper methods instead of instantiating a ``Contents`` class
+directly:
+
+contents_for_items
+-------------------
+
+Returns a contents instance for a list of main models:
+
+.. code-block:: python
+
+    articles = Article.objects.all()[:10]
+    contents = contents_for_items(
+        articles,
+        plugins=[RichText, Download],
+    )
+
+    something = [
+        (article, contents[article])
+        for article in articles
+    ]
+
+contents_for_item
+------------------
+
+Returns the contents instance for a given main model (note that this
+helper calls ``contents_for_items`` to do the real work):
+
+.. code-block:: python
+
+    # ...
+    contents = contents_for_item(
+        article,
+        plugins=[RichText, Download],
+    )
+
+It is also possible to add additional items for inheriting regions.
+This is most useful with a page tree where i.e. sidebar contents are
+inherited from ancestors (this example uses methods added by
+django-tree-queries_ as used in feincms3_):
+
+.. code-block:: python
+
+    page = ...
+    contents = contents_for_item(
+        page,
+        plugins=[RichText, Download],
+        page.ancestors().reverse(),  # Prefer content closer to the
+                                     # current page
+    )
+
+.. _FeinCMS: https://github.com/feincms/feincms/
+.. _django-tree-queries: https://github.com/matthiask/django-tree-queries/
+.. _feincms3: https://feincms3.readthedocs.io/

docs/design-decisions.rst

@@ -0,0 +1,72 @@
+================
+Design Decisions
+================
+
+About rich text editors
+========================
+
+We have been struggling with rich text editors for a long time. To
+be honest, I do not think it was a good idea to add that many
+features to the rich text editor. Resizing images uploaded into a
+rich text editor is a real pain, and what if you'd like to reuse
+these images or display them using a lightbox script or something
+similar? You have to resort to writing loads of JavaScript code
+which will only work on one browser. You cannot really filter the
+HTML code generated by the user to kick out ugly HTML code generated
+by copy-pasting from word. The user will upload 10mb JPEGs and
+resize them to 50x50 pixels in the rich text editor.
+
+All of this convinced me that offering the user a rich text editor
+with too much capabilities is a really bad idea. The rich text
+editor in FeinCMS only has bold, italic, bullets, link and headlines
+activated (and the HTML code button, because that's sort of
+inevitable -- sometimes the rich text editor messes up and you
+cannot fix it other than going directly into the HTML code.  Plus,
+if someone really knows what they are doing, I'd still like to give
+them the power to shot their own foot).
+
+If this does not seem convincing you can always add your own rich
+text plugin with a different configuration (or just override the
+rich text editor initialization template in your own project). We do
+not want to force our world view on you, it's just that we think
+that in this case, more choice has the bigger potential to hurt than
+to help.
+
+Plugins
+=======
+
+Images and other media files are inserted via objects; the user can
+only select a file and a display mode (f.e. float/block for images
+or something...). An article's content could look like this:
+
+* Rich Text
+* Floated image
+* Rich Text
+* YouTube Video Link, embedding code is automatically generated from
+  the link
+* Rich Text
+
+It's of course easier for the user to start with only a single rich
+text field, but I think that the user already has too much confusing
+possibilities with an enhanced rich text editor. Once the user
+grasps the concept of content blocks which can be freely added,
+removed and reordered using drag/drop, I'd say it's much easier to
+administer the content of a webpage. Plus, the content blocks can
+have their own displaying and updating logic; implementing dynamic
+content inside the CMS is not hard anymore, on the contrary. Since
+content blocks are Django models, you can do anything you want
+inside them.
+
+Glossary
+========
+
+- **Main model**: (Bad wording -- not happy with that). The model to
+  which plugins may be added. This model uses the content editor
+  admin class.
+
+- **Plugin**: A content element type such as rich text, download,
+  and image or whatever.
+
+- **Content block**: A content element instance belonging to a main
+  model instance. Also called **item** sometimes in the documentation
+  above.