docs: Update documentation

docs/conf.py

@@ -78,7 +78,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -189,4 +189,4 @@
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ["search.html"]
 
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/", None)}

docs/requirements.txt

@@ -1,2 +1,4 @@
 sphinx
 sphinxcontrib-spelling
+sphinx-copybutton
+furo

docs/settings.rst

@@ -23,10 +23,40 @@ Settings for djangocms Versioning
     deleted (if the user has the appropriate rights).
 
 
-.. py:attribute: DJANGOCMS_VERSIONING_LOCK_VERSIONS
+.. py:attribute:: DJANGOCMS_VERSIONING_ENABLE_MENU_REGISTRATION
+
+    Defaults to ``True``
+
+    This settings specifies if djangocms-versioning should register its own
+    versioned CMS menu.
+
+    The versioned CMS menu also shows draft content in edit and preview mode.
+
+
+.. py:attribute:: DJANGOCMS_VERSIONING_LOCK_VERSIONS
 
     Defaults to ``False``
 
-    This setting controls if draft versions are locked. If they are, only the user 
-    who created the draft can change the draft. See :ref:`locking versions` for more
-    details.
+    This setting controls if draft versions are locked. If they are, only the user
+    who created the draft can change the draft. See
+    :ref:`Locking versions <locking-versions>` for more details.
+
+
+.. py:attribute:: DJANGOCMS_VERSIONING_USERNAME_FIELD
+
+    Defaults to ``"username"``
+
+    Adjust this settings if your custom ``User`` model does contain a username
+    field which has a different name.
+
+
+.. py:attribute:: DJANGOCMS_VERSIONING_DEFAULT_USER
+
+    Defaults to ``None``
+
+    Creating versions require a user. For management commands (including
+    migrations) either a user can be provided or this default user is
+    used. If not set and no user is specified for the management command, it
+    will fail.
+
+

docs/upgrade/2.0.0.rst

@@ -4,7 +4,7 @@
 2.0.0 release notes (unreleased)
 ********************************
 
-*Date in 2023*
+*October 2023*
 
 Welcome to django CMS versioning 2.0.0!
 
@@ -55,6 +55,14 @@ object nor the grouper object can be deleted. To allow deletion of ``Version``
 objects set ``DJANGOCMS_VERSIONING_ALLOW_DELETING_VERSIONS`` to ``True`` in
 the project's ``settings.py``.
 
+Version-locking
+---------------
+
+Previously a separate package, djangocms-version-locking has now been included
+in djangocms-versioning. Upon setting ``DJANGOCMS_VERSIONING_LOCK_VERSIONS`` to
+``True``, draft versions will be locked by default and can only be edited by
+the person who created the draft. This is to avoid conflicts in certain
+editorial situations.
 
 Backwards incompatible changes in 2.0.0
 =======================================
@@ -67,6 +75,13 @@ Monkey patching
 * As a result monkey patching has been removed from djangocms-versioning and
   is discouraged
 
+Accessing helper functions
+--------------------------
+* Direct imports from djangocms_versioning are discouraged. They block drop-in
+  replacements of djangocms_versioning.
+* ``djangocms_verisoning.helpers.remove_published_where`` has been removed.
+  Use the ``admin_manager`` of a verisoned content object instead.
+
 Title Extension
 ---------------
 

docs/version_locking.rst

@@ -1,19 +1,20 @@
+.. _locking-versions:
 
-**************************
+****************
 Locking versions
-**************************
+****************
 
 Explanation
 -----------
 The lock versions setting is intended to modify the way djangocms-versioning works in the following way:
 
- - A version is **locked to its author** when a draft is created.
- - The lock prevents editing of the draft by anyone other than the author.
- - That version becomes automatically unlocked again once it is published.
- - Locks can be removed by a user with the correct permission (``delete_versionlock``)
- - Unlocking an item sends an email notification to the author to which it was locked.
- - Manually unlocking a version does not lock it to the unlocking user, nor does it change the author.
- - The Version admin view for each versioned content-type shows lock icons and offers unlock actions
+- A version is **locked to its author** when a draft is created.
+- The lock prevents editing of the draft by anyone other than the author.
+- That version becomes automatically unlocked again once it is published.
+- Locks can be removed by a user with the correct permission (``delete_versionlock``)
+- Unlocking an item sends an email notification to the author to which it was locked.
+- Manually unlocking a version does not lock it to the unlocking user, nor does it change the author.
+- The Version admin view for each versioned content-type shows lock icons and offers unlock actions
 
 Activation
 ----------

docs/versioning_integration.rst

@@ -146,6 +146,23 @@ For more details on how `cms_config.py` integration works please check the docum
 for django-cms>=4.0.
 
 
+Accessing content model objects
+-------------------------------
+
+Versioned content model objects have a customized ``objects`` manager which by
+default only creates querysets that return published versions of the content
+object. This will ensure that only published objects are visible to the public.
+
+In some situations, namely when working in the admin, it is helpful to also have
+other content objects available, e.g. when linking to a not-yet-published object.
+
+Versioned objects therefore also have an additional manager ``admin_manager``
+which can access all objects. To get all draft blog posts, you can write
+``PostContent.admin_manager.filter(versions__state=DRAFT)``. Since the
+``admin_manager`` has access to non-public information it should only be
+used inside the Django admin (hence its name).
+
+
 Implement a custom copy function
 ---------------------------------
 Whilst simple model structures should be fine using the `default_copy` function,