Merge pull request #2 from django-cms/add/publishing-explanation

feat: Add explanation for publishing workflow. Format uniformly.

.github/workflows/docs.yml

@@ -26,7 +26,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-pip-
       - run: python -m pip install -r user-guide/requirements.txt
-      - run: codespell -w user-guide
+      - run: codespell -w user-guide/source
       - name: Build docs
         run: |
           cd user-guide

user-guide/requirements.in

@@ -13,3 +13,4 @@ django~=4.2
 git+https://github.com/django-cms/django-cms@release/4.1.x
 codespell
 pip-tools
+docstrfmt

user-guide/requirements.txt

@@ -1,144 +1,180 @@
 #
-# This file is autogenerated by pip-compile with python 3.10
-# To update, run:
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
 #
-#    pip-compile
+#    pip-compile --output-file=requirements.txt requirements.in
 #
-alabaster==0.7.12
+alabaster==0.7.13
     # via sphinx
-asgiref==3.5.2
+asgiref==3.7.2
     # via django
-babel==2.11.0
+babel==2.14.0
     # via sphinx
-beautifulsoup4==4.11.1
+beautifulsoup4==4.12.2
     # via furo
-build==0.9.0
+black==23.12.1
+    # via docstrfmt
+build==1.0.3
     # via pip-tools
-certifi==2022.12.7
+certifi==2023.11.17
     # via requests
-charset-normalizer==2.1.1
+charset-normalizer==3.3.2
     # via requests
-click==8.1.3
-    # via pip-tools
-codespell==2.2.2
+click==8.1.7
+    # via
+    #   black
+    #   docstrfmt
+    #   pip-tools
+codespell==2.2.6
     # via -r requirements.in
 colorama==0.4.6
     # via sphinx-autobuild
-coverage==6.5.0
+coverage==7.4.0
     # via -r requirements.in
-datetime==4.7
+datetime==5.4
     # via -r requirements.in
-django==3.2.16
+django==4.2.8
     # via
     #   -r requirements.in
     #   django-classy-tags
     #   django-cms
     #   django-formtools
     #   django-sekizai
     #   django-treebeard
-django-classy-tags==3.0.1
+    #   djangocms-admin-style
+django-classy-tags==4.1.0
     # via
     #   django-cms
     #   django-sekizai
-django-cms @ git+https://github.com/django-cms/django-cms@develop-4
+django-cms @ git+https://github.com/django-cms/django-cms@release/4.1.x
     # via -r requirements.in
-django-formtools==2.4
+django-formtools==2.5.1
     # via django-cms
-django-sekizai==3.0.1
+django-sekizai==4.1.0
     # via django-cms
-django-treebeard==4.5.1
+django-treebeard==4.7
     # via django-cms
-djangocms-admin-style==3.2.0
+djangocms-admin-style==3.2.6
     # via django-cms
-docutils==0.19
-    # via sphinx
-furo==2022.12.7
+docstrfmt==1.6.1
     # via -r requirements.in
-idna==3.4
+docutils==0.20.1
+    # via
+    #   docstrfmt
+    #   sphinx
+furo==2023.9.10
+    # via -r requirements.in
+idna==3.6
     # via requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.2
     # via sphinx
+libcst==1.1.0
+    # via docstrfmt
 livereload==2.6.3
     # via sphinx-autobuild
-markupsafe==2.1.1
+markupsafe==2.1.3
     # via
     #   -r requirements.in
     #   jinja2
-packaging==21.3
+mypy-extensions==1.0.0
+    # via
+    #   black
+    #   typing-inspect
+packaging==23.2
     # via
+    #   black
     #   build
     #   django-cms
     #   sphinx
-pep517==0.13.0
-    # via build
-pip-tools==6.9.0
+pathspec==0.12.1
+    # via black
+pip-tools==7.3.0
     # via -r requirements.in
+platformdirs==4.1.0
+    # via
+    #   black
+    #   docstrfmt
 pyenchant==3.2.2
     # via
     #   -r requirements.in
     #   sphinxcontrib-spelling
-pygments==2.13.0
+pygments==2.17.2
     # via
     #   -r requirements.in
     #   furo
     #   sphinx
-pyparsing==3.0.9
-    # via packaging
-pytz==2022.6
-    # via
-    #   babel
-    #   datetime
-    #   django
-requests==2.28.1
+pyproject-hooks==1.0.0
+    # via build
+pytz==2023.3.post1
+    # via datetime
+pyyaml==6.0.1
+    # via libcst
+requests==2.31.0
     # via sphinx
 six==1.16.0
     # via livereload
 snowballstemmer==2.2.0
     # via sphinx
-soupsieve==2.3.2.post1
+soupsieve==2.5
     # via beautifulsoup4
-sphinx==5.3.0
+sphinx==7.2.6
     # via
     #   -r requirements.in
+    #   docstrfmt
     #   furo
     #   sphinx-autobuild
     #   sphinx-basic-ng
     #   sphinx-copybutton
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
     #   sphinxcontrib-spelling
     #   sphinxext-opengraph
 sphinx-autobuild==2021.3.14
     # via -r requirements.in
-sphinx-basic-ng==1.0.0b1
+sphinx-basic-ng==1.0.0b2
     # via furo
-sphinx-copybutton==0.5.1
+sphinx-copybutton==0.5.2
     # via -r requirements.in
-sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-applehelp==1.0.7
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==1.0.5
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-htmlhelp==2.0.4
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==1.0.6
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.9
     # via sphinx
-sphinxcontrib-spelling==7.6.2
+sphinxcontrib-spelling==8.0.0
     # via -r requirements.in
-sphinxext-opengraph==0.7.5
+sphinxext-opengraph==0.9.1
     # via -r requirements.in
-sqlparse==0.4.3
+sqlparse==0.4.4
     # via django
-tornado==6.2
+tabulate==0.9.0
+    # via docstrfmt
+toml==0.10.2
+    # via docstrfmt
+tornado==6.4
     # via livereload
-urllib3==1.26.12
+typing-extensions==4.9.0
+    # via
+    #   libcst
+    #   typing-inspect
+typing-inspect==0.9.0
+    # via libcst
+urllib3==2.1.0
     # via requests
-wheel==0.38.3
+wheel==0.42.0
     # via pip-tools
-zope-interface==5.5.1
+zope-interface==6.1
     # via datetime
 
 # The following packages are considered to be unsafe in a requirements file:

user-guide/source/explanation/aliases.rst

@@ -1,21 +1,30 @@
 Aliases
-#######
+=======
 
-.. include:: ../alias-note.rst
+.. include:: ../alias-note.include
 
-
-In Django CMS, the Alias plugin is a powerful tool that enables content editors to display in as many places as they like without duplicating it. Essentially, it creates a reference or link to content that resides in a separate place - called an "Alias".
+In Django CMS, the Alias plugin is a powerful tool that enables content editors to
+display in as many places as they like without duplicating it. Essentially, it creates a
+reference or link to content that resides in a separate place - called an "Alias".
 
 Key aspects of the Alias plugin include:
 
-1. **Content Replication:** Rather than copying content, the alias content is referenced either in a page template or by using the Alias plugin.
-
-2. **Cross-Page Content Sharing:** It facilitates sharing content across different pages within the site. For instance, if there's a section that needs to appear in multiple places but should have consistent content, the aliases can be employed to achieve this.
-
-3. **Maintaining Consistency:** Using aliases ensures consistency in content across various parts of the website. If the original content gets updated, all aliases referencing it will reflect those changes instantly.
-
-4. **Saves Effort and Reduces Errors:** Instead of manually replicating content across multiple pages (which could lead to discrepancies or errors), the Alias plugin streamlines the process and reduces the chance of inconsistencies.
-
-5. **Ease of Management:** Content editors can manage content in one place while displaying it in multiple locations, making it easier to maintain and update information without having to navigate through numerous pages.
-
-In essence, aliases in Django CMS serves as a smart reference system, allowing content editors to reuse existing content across the site while maintaining consistency and efficiency in content management.
+1. **Content Replication:** Rather than copying content, the alias content is referenced
+   either in a page template or by using the Alias plugin.
+2. **Cross-Page Content Sharing:** It facilitates sharing content across different pages
+   within the site. For instance, if there's a section that needs to appear in multiple
+   places but should have consistent content, the aliases can be employed to achieve
+   this.
+3. **Maintaining Consistency:** Using aliases ensures consistency in content across
+   various parts of the website. If the original content gets updated, all aliases
+   referencing it will reflect those changes instantly.
+4. **Saves Effort and Reduces Errors:** Instead of manually replicating content across
+   multiple pages (which could lead to discrepancies or errors), the Alias plugin
+   streamlines the process and reduces the chance of inconsistencies.
+5. **Ease of Management:** Content editors can manage content in one place while
+   displaying it in multiple locations, making it easier to maintain and update
+   information without having to navigate through numerous pages.
+
+In essence, aliases in Django CMS serves as a smart reference system, allowing content
+editors to reuse existing content across the site while maintaining consistency and
+efficiency in content management.

user-guide/source/explanation/index.rst

@@ -1,20 +1,19 @@
 .. _user-explanation:
 
-########
 Concepts
-########
+========
 
 .. include:: ../contribute-note.include
 
-django CMS uses some specific concepts. This section explains those concepts from a content editor perspective.
+django CMS uses some specific concepts. This section explains those concepts from a
+content editor perspective.
 
 .. toctree::
     :maxdepth: 1
 
     placeholders
     plugins
     publishing
-    version-locking
     aliases
     structure-content-modes
     touch

user-guide/source/explanation/placeholders.rst

@@ -1,12 +1,29 @@
 Placeholders
-############
+============
 
-In Django CMS, placeholders are special markers within templates that define regions where content can be edited and managed by content editors. These placeholders act as slots or containers within a template where various types of content can be added, modified, and rearranged through django CMS' frontend editor and its structure board.
+In Django CMS, placeholders are special markers within templates that define regions
+where content can be edited and managed by content editors. These placeholders act as
+slots or containers within a template where various types of content can be added,
+modified, and rearranged through django CMS' frontend editor and its structure board.
 
 Here's how placeholders work:
 
-1. **Defined Areas in a page:** Designers identify specific areas within their HTML templates where content can be dynamically inserted. Editors can access these defined placeholders and add or edit content directly through the user-friendly frontend editing interface without needing to touch the underlying code. Pages can be rendered using different templates.
-2. **Content Manipulation:** Editors interact with placeholders to add various types of content elements or plugins (such as text, images, videos, forms, etc.) to these designated areas. They can modify existing content, rearrange elements, or remove content as needed.
-3. **Flexibility and Customization:** Django CMS allows for the creation of custom plugins that can be inserted into placeholders. These plugins offer a wide range of functionalities and content types, giving content editors the flexibility to create diverse and engaging web pages without requiring developer intervention for each content update.
+1. **Defined Areas in a page:** Designers identify specific areas within their HTML
+   templates where content can be dynamically inserted. Editors can access these defined
+   placeholders and add or edit content directly through the user-friendly frontend
+   editing interface without needing to touch the underlying code. Pages can be rendered
+   using different templates.
+2. **Content Manipulation:** Editors interact with placeholders to add various types of
+   content elements or plugins (such as text, images, videos, forms, etc.) to these
+   designated areas. They can modify existing content, rearrange elements, or remove
+   content as needed.
+3. **Flexibility and Customization:** Django CMS allows for the creation of custom
+   plugins that can be inserted into placeholders. These plugins offer a wide range of
+   functionalities and content types, giving content editors the flexibility to create
+   diverse and engaging web pages without requiring developer intervention for each
+   content update.
 
-Ultimately, placeholders in Django CMS facilitate a clear separation between the presentation layer (templates) and the content, enabling content editors to manage and update website content easily without needing extensive technical knowledge or modifying the underlying code.
+Ultimately, placeholders in Django CMS facilitate a clear separation between the
+presentation layer (templates) and the content, enabling content editors to manage and
+update website content easily without needing extensive technical knowledge or modifying
+the underlying code.

user-guide/source/explanation/plugins.rst

@@ -1,14 +1,30 @@
 Plugins
-#######
+=======
 
-Django CMS plugins are modular components that represent content. In Django CMS, content components are organized into placeholders within templates. These placeholders can be filled with various plugins to add diverse content components.
+Django CMS plugins are modular components that represent content. In Django CMS, content
+components are organized into placeholders within templates. These placeholders can be
+filled with various plugins to add diverse content components.
 
-Django CMS plugins offer content editors an intuitive way to manage and enrich the content of web pages without needing technical expertise or diving into code. Here's how they benefit content editors:
+Django CMS plugins offer content editors an intuitive way to manage and enrich the
+content of web pages without needing technical expertise or diving into code. Here's how
+they benefit content editors:
 
-1. **Ease of Use:** Content editors can work inside the frontend editor and use the structure board, where they can see available placeholders on a page. They can easily add, edit, or remove content elements (plugins) within these placeholders using a simple drag-and-drop interface or form-based interactions.
+1. **Ease of Use:** Content editors can work inside the frontend editor and use the
+   structure board, where they can see available placeholders on a page. They can easily
+   add, edit, or remove content elements (plugins) within these placeholders using a
+   simple drag-and-drop interface or form-based interactions.
+2. **Content Variety:** Plugins provide a wide range of content types that can be
+   inserted into placeholders, such as text, images, videos, galleries, sliders, forms,
+   maps, and more. This variety enables editors to create rich and diverse web pages
+   without relying on developers for every content update.
+3. **Customization:** While there's a set of default plugins available, each
+   installation has its own set of plugins activated and might also use custom plugins
+   tailored to specific needs. These custom plugins can encapsulate complex
+   functionalities or unique design elements that content editors might require for
+   their content. Those custom plugins are not within the scope of this user guide.
 
-2. **Content Variety:** Plugins provide a wide range of content types that can be inserted into placeholders, such as text, images, videos, galleries, sliders, forms, maps, and more. This variety enables editors to create rich and diverse web pages without relying on developers for every content update.
-
-3. **Customization:** While there's a set of default plugins available, each installation has its own set of plugins activated and might also use custom plugins tailored to specific needs. These custom plugins can encapsulate complex functionalities or unique design elements that content editors might require for their content. Those custom plugins are not within the scope of this user guide.
-
-In essence, Django CMS plugins empower content editors to manage and present content effectively, providing them with the tools to create engaging and dynamic web experiences without needing to delve into the technical intricacies of web development. These plugins empower editors to create and manage content without needing to write code or modify templates each time they want to add specific elements to a webpage.
+In essence, Django CMS plugins empower content editors to manage and present content
+effectively, providing them with the tools to create engaging and dynamic web
+experiences without needing to delve into the technical intricacies of web development.
+These plugins empower editors to create and manage content without needing to write code
+or modify templates each time they want to add specific elements to a webpage.