📝: merge docs from master

.github/workflows/bandit.yml

@@ -0,0 +1,52 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# Bandit is a security linter designed to find common security issues in Python code.
+# This action will run Bandit on your codebase.
+# The results of the scan will be found under the Security tab of your repository.
+
+# https://github.com/marketplace/actions/bandit-scan is ISC licensed, by abirismyname
+# https://pypi.org/project/bandit/ is Apache v2.0 licensed, by PyCQA
+
+name: Bandit
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "master" ]
+  schedule:
+    - cron: '15 22 * * 2'
+
+jobs:
+  bandit:
+    permissions:
+      contents: read # for actions/checkout to fetch code
+      security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
+      actions: read # only required for a private repository by github/codeql-action/upload-sarif to get the Action run status
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Bandit Scan
+        uses: shundor/python-bandit-scan@9cc5aa4a006482b8a7f91134412df6772dbda22c
+        with: # optional arguments
+          # exit with 0, even with results found
+          exit_zero: true # optional, default is DEFAULT
+          # Github token of the repository (automatically created by Github)
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Needed to get PR information.
+          # File or directory to run bandit on
+          # path: # optional, default is .
+          # Report only issues of a given severity level or higher. Can be LOW, MEDIUM or HIGH. Default is UNDEFINED (everything)
+          # level: # optional, default is UNDEFINED
+          # Report only issues of a given confidence level or higher. Can be LOW, MEDIUM or HIGH. Default is UNDEFINED (everything)
+          # confidence: # optional, default is UNDEFINED
+          # comma-separated list of paths (glob patterns supported) to exclude from scan (note that these are in addition to the excluded paths provided in the config file) (default: .svn,CVS,.bzr,.hg,.git,__pycache__,.tox,.eggs,*.egg)
+          # excluded_paths: # optional, default is DEFAULT
+          # comma-separated list of test IDs to skip
+          # skips: # optional, default is DEFAULT
+          # path to a .bandit file that supplies command line arguments
+          # ini_path: # optional, default is DEFAULT
+

docs/source/index.rst

@@ -7,8 +7,8 @@ wagtailmenus is an open-source extension for `Wagtail CMS
 
 The current version is tested for compatibility with the following:
 
-- Wagtail versions >= 4.1
-- Django versions 3.2, 4.1, and 4.2
+- Wagtail versions >= 5.2
+- Django versions 3.2, 4.2 and >= 5.0
 - Python versions 3.8 to 3.12
 
 To find out more about what wagtailmenus does and why, see :doc:`overview`

docs/source/installation.rst

@@ -10,7 +10,7 @@ Installing wagtailmenus
 
         pip install wagtailmenus
 
-2.  Add ``wagtailmenus`` and ``modeladmin`` to the
+2.  Add ``wagtailmenus`` to the
     ``INSTALLED_APPS`` setting in your project settings:
 
     .. code-block:: python

docs/source/releases/4.0.rst

@@ -1,6 +1,6 @@
-===============================================
-Wagtailmenus 4.0.0 release notes (28.02.2023)
-===============================================
+===========================================
+Wagtailmenus 4.0 release notes (28.02.2024)
+===========================================
 
 .. contents::
     :local:
@@ -10,11 +10,46 @@ Wagtailmenus 4.0.0 release notes (28.02.2023)
 What's new?
 ===========
 
-This completes the migration from Wagtail `model-admin` functionality to `snippets` functionality, introduced in Wagtail 5.0 and deprecated in Wagtail 6.0. `wagtail-menus` is now compatible with Wagtail 6.0 and Python 3.12.
+Wagtailmenus now uses Snippets
+------------------------------
 
-Django 4.1 is no longer supported; the minimum version is now Django 4.2.
+Wagtailmenus prior to this release used the Wagtail ModelAdmin contrib package for menu administration.
+With the deprecation of ModelAdmin in Wagtail 5.2 and its removal in Wagtail 6, Wagtail's enhanced Snippet capability is now used for menu admin.
 
-Minor changes & bug fixes
-=========================
+This release retains all the functionality of wagtailmenus 3.1.9, however the admin user interface has changed consistent with the revised look in Wagtail 5.2 and 6.
+Any existing menu configuration is retained.
 
+Upgrade considerations
+======================
 
+Migration from ModelAdmin to Snippets
+-------------------------------------
+
+The two menu administration ViewSets, ``MainMenuAdmin`` and ``FlatMenuAdmin``, are now based on ``SnippetViewSet``.
+
+Ensure wagtail.snippets is in your INSTALLED_APPS:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        ...,
+        'wagtail.snippets',
+        ...,
+    ]
+
+If `wagtailmenus` is your code's last dependency on `ModelAdmin`,
+then you can remove `wagtail_modeladmin` or `wagtail.contrib.modeladmin` from your `INSTALLED_APPS` and if present, from your `requirements.txt` file.
+
+Customised Admin Classes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have customised either of ``MainMenuAdmin`` and ``FlatMenuAdmin``,
+you will need to refactor your code to be compatible with ``SnippetViewSet`` behaviour.
+The guide at `Migrating from ModelAdmin to Snippets <https://docs.wagtail.org/en/v5.2.3/reference/contrib/modeladmin/migrating_to_snippets.html>`_ in the Wagtail documentation may assist with this task.
+
+You will need to assign the newly customised admin classes to the following settings:
+
+- ``WAGTAILMENUS_MAIN_MENUS_ADMIN_CLASS``. This replaces ``WAGTAILMENUS_MAIN_MENUS_MODELADMIN_CLASS``
+- ``WAGTAILMENUS_FLAT_MENUS_ADMIN_CLASS``. This replaces ``WAGTAILMENUS_FLAT_MENUS_MODELADMIN_CLASS``
+
+Note that ``MainMenuAdmin`` and ``FlatMenuAdmin`` are now in the ``wagtailmenus.menuadmin`` module, and that the ``wagtailmenus.modeladmin`` module has been removed.

docs/source/releases/index.rst

@@ -5,6 +5,7 @@ Release notes
 .. toctree::
     :maxdepth: 1
 
+    4.0
     3.1.9
     3.1.8
     3.1.7

docs/source/settings_reference.rst

@@ -71,18 +71,18 @@ By default, 'Flat menus' are editable in the Wagtail CMS. Setting this to ``Fals
 
 .. _FLAT_MENUS_MODELADMIN_CLASS:
 
-``WAGTAILMENUS_FLAT_MENUS_MODELADMIN_CLASS``
+``WAGTAILMENUS_FLAT_MENUS_ADMIN_CLASS``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Default value: ``'wagtailmenus.modeladmin.FlatMenuAdmin'``
+Default value: ``'wagtailmenus.menuadmin.FlatMenuAdmin'``
 
-If you wish to override the ``ModelAdmin`` class used to represent **'Flat menus'** in the Wagtail admin area for your project (e.g. to display additional custom fields in the listing view, or change/add new views), you can do so by using this setting to swap out the default class for a custom one. e.g.
+If you wish to override the admin class used to represent **'Flat menus'** in the Wagtail admin area for your project (e.g. to display additional custom fields in the listing view, or change/add new views), you can do so by using this setting to swap out the default class for a custom one. e.g.
 
 .. code-block:: python
 
     # e.g. settings/base.py
 
-    WAGTAILMENUS_FLAT_MENUS_MODELADMIN_CLASS = "projectname.appname.modulename.ClassName"
+    WAGTAILMENUS_FLAT_MENUS_ADMIN_CLASS = "projectname.appname.modulename.ClassName"
 
 
 The value should be an import path string, rather than a direct pointer to the class itself. wagtailmenus will lazily import the class from this path when it is required. If the path is invalid, an ``ImproperlyConfigured`` exception will be raised.
@@ -110,12 +110,12 @@ By default, 'Main menus' are editable in the Wagtail CMS. Setting this to ``Fals
 
 .. _MAIN_MENUS_MODELADMIN_CLASS:
 
-``WAGTAILMENUS_MAIN_MENUS_MODELADMIN_CLASS``
+``WAGTAILMENUS_MAIN_MENUS_ADMIN_CLASS``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Default value: ``'wagtailmenus.modeladmin.MainMenuAdmin'``
+Default value: ``'wagtailmenus.menuadmin.MainMenuAdmin'``
 
-If you wish to override the ``ModelAdmin`` class used to represent **'Main menus'** in the Wagtail admin area for your project (e.g. to display additional custom fields in the listing view, or change/add new views), you can do so by using this setting to swap out the default class for a custom one. e.g.
+If you wish to override the admin class used to represent **'Main menus'** in the Wagtail admin area for your project (e.g. to display additional custom fields in the listing view, or change/add new views), you can do so by using this setting to swap out the default class for a custom one. e.g.
 
 .. code-block:: python
 

setup.py

@@ -69,9 +69,9 @@
         'Programming Language :: Python :: 3.12',
         'Framework :: Django',
         'Framework :: Django :: 3.2',
-        'Framework :: Django :: 4.1',
         'Framework :: Django :: 4.2',
         'Framework :: Wagtail :: 5',
+        'Framework :: Wagtail :: 6',
         'Topic :: Internet :: WWW/HTTP',
         "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
     ],

tox.ini

@@ -3,9 +3,7 @@ skipsdist = True
 usedevelop = True
 
 envlist =
-    wt42-dj41-py310
     wt52-dj32-py{38,39,310}
-    wt52-dj41-py{38,39,310,311}
     wt52-dj42-py{38,39,310,311,312}
     wt52-dj50-py{310,311,312}
     wt60-dj42-py{38,39,310,311,312}

wagtailmenus/conf/defaults.py

@@ -9,15 +9,15 @@
 
 FLAT_MENUS_EDITABLE_IN_WAGTAILADMIN = True
 
-FLAT_MENUS_ADMIN_CLASS = 'wagtailmenus.modeladmin.FlatMenuAdmin'
+FLAT_MENUS_ADMIN_CLASS = 'wagtailmenus.menuadmin.FlatMenuAdmin'
 
 FLAT_MENUS_HANDLE_CHOICES = None
 
 MAINMENU_MENU_ICON = 'list-ol'
 
 MAIN_MENUS_EDITABLE_IN_WAGTAILADMIN = True
 
-MAIN_MENUS_ADMIN_CLASS = 'wagtailmenus.modeladmin.MainMenuAdmin'
+MAIN_MENUS_ADMIN_CLASS = 'wagtailmenus.menuadmin.MainMenuAdmin'
 
 USE_CONDENSEDINLINEPANEL = True
 

wagtailmenus/conf/tests/test_modeladmin_disable_settings.py → wagtailmenus/conf/tests/test_menuadmin_disable_settings.py

@@ -4,7 +4,7 @@
 from django.test import TestCase, override_settings
 
 from wagtailmenus import wagtail_hooks
-from wagtailmenus.modeladmin import FlatMenuAdmin, MainMenuAdmin
+from wagtailmenus.menuadmin import FlatMenuAdmin, MainMenuAdmin
 
 modeladmin_register_str = 'wagtail.snippets.models.register_snippet'
 

wagtailmenus/tests/menuadmin.py

@@ -0,0 +1,9 @@
+from wagtailmenus.menuadmin import FlatMenuAdmin, MainMenuAdmin
+
+
+class CustomFlatMenuAdmin(FlatMenuAdmin):
+    pass
+
+
+class CustomMainMenuAdmin(MainMenuAdmin):
+    pass