Feature: djangocms 4.0.x documentation updates (#7007)

docs/4.0.x/packages.md

@@ -0,0 +1,44 @@
+## Packages
+
+## django-filer
+
+- versioning-filer adds some oppinionated filer model replacements. This needs to be rethought as we cannot replace all filer models in all plugins (backwards incompatibility). This would hurt the existing addons-ecosystem.
+
+## djangocms-history
+
+- this package will not work anymore in 4.x, instead it's functionality should be integrated into djangocms-versioning (simplistic undo/redo functionality)
+
+## djangocms-url-manager
+
+- djangocms-url-manager redefines how URLs are managed and as such djangocms-link, or any other link plugin, will need to be adapted to its use case. We need to check if this will be part of the core system as well.
+
+## djangocms-moderation
+
+- Further docs on how to use the functionality can be found here: https://github.com/django-cms/djangocms-moderation/tree/release/1.0.x/docs
+
+
+### Core Packages
+
+| Package                     | Package Name               | Codebase                                                            | Documentation                                                                  |
+| --------------------------- | -------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Django CMS CKEditor 4.x     | Djangocms_text_ckeditor    | https://github.com/divio/djangocms-text-ckeditor/tree/support/4.0.x | https://github.com/divio/djangocms-text-ckeditor/blob/support/4.0.x/README.rst |
+| Django CMS Alias            | djangocms_alias            | https://github.com/divio/djangocms-alias                            | https://github.com/divio/djangocms-alias/blob/master/README.rst                |
+| Django CMS Url Manager      | djangocms_url_manager      | https://github.com/divio/djangocms-url-manager                      | https://github.com/divio/djangocms-url-manager/blob/master/README.rst          |
+| Django CMS Versioning       | djangocms_versioning       | https://github.com/divio/djangocms-versioning                       | https://divio-djangocms-versioning.readthedocs-hosted.com/en/latest/           |
+
+### Optional Packages
+
+| Package                     | Package Name               | Codebase                                                            | Documentation                                                                  |
+| --------------------------- | -------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Django CMS Moderation       | djangocms_moderation       | https://github.com/divio/djangocms-moderation/tree/release/1.0.x    | https://github.com/divio/djangocms-moderation/tree/release/1.0.x/docs          |
+| Django CMS Filer Versioning | djangocms_versioning_filer | https://github.com/divio/djangocms-versioning-filer                 | https://github.com/divio/djangocms-versioning-filer/blob/master/README.rst     |
+
+### Third party opinionated packages
+
+| Package                    | Package Name              | Codebase                                                           | Documentation                                                                             |
+| -------------------------- | ------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| Django CMS Version Locking | djangocms_version_locking | https://github.com/FidelityInternational/djangocms-version-locking | https://github.com/FidelityInternational/djangocms-version-locking/blob/master/README.rst |
+| Django CMS Page Admin      | djangocms_pageadmin       | https://github.com/FidelityInternational/djangocms-pageadmin       | https://github.com/FidelityInternational/djangocms-pageadmin/tree/master/docs             |
+| Django CMS Navigation      | djangocms_navigation      | https://github.com/FidelityInternational/djangocms-navigation      | https://github.com/FidelityInternational/djangocms-navigation/blob/master/README.rst      |
+| Django CMS References      | djangocms_references      | https://github.com/FidelityInternational/djangocms-references      | https://github.com/FidelityInternational/djangocms-references/tree/master/docs            |
+| Django CMS FIL Admin Style | djangocms_fil_admin_style | https://github.com/FidelityInternational/djangocms-fil-admin-style |                                                                                           |

docs/Makefile

@@ -1,18 +1,22 @@
 # Makefile for Sphinx documentation
-#
-
 # You can set these variables from the command line.
+
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
+VENV = env/bin/activate
+PORT = 8001
+BUILDDIR      = build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -n -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
+# list the targets that we don't want confused with files in the directory
 .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
 
+# "help" is first so that "make" without an argument acts like "make help".
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
@@ -28,13 +32,29 @@ help:
 	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
 	@echo "  spelling  to check for typos in documentation"
 
-clean:
-	-rm -rf build/*
 
 html:
 	. $(VENV); $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
+	sphinx-build -b html  -n -d build/doctrees -D latex_paper_size=a4  -D latex_paper_size=letter build/html
+
+install:
+	@echo "... setting up virtualenv"
+	python3 -m venv env
+	. $(VENV); pip install -r requirements.txt
+
+	@echo "\n" \
+	      "-------------------------------------------------------------------------------------------------- \n" \
+		    "* watch, build and serve the documentation: make run \n" \
+		    "* check spelling: make spelling \n" \
+		    "\n" \
+				"enchant must be installed in order for pyenchant (and therefore spelling checks) to work. See \n" \
+				"http://docs.django-cms.org/en/latest/contributing/documentation.html#install-the-spelling-software \n" \
+	      "-------------------------------------------------------------------------------------------------- \n" \
+
+clean:
+	-rm -r $(BUILDDIR)/*
 
 dirhtml:
 	. $(VENV); $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) build/dirhtml
@@ -95,23 +115,5 @@ spelling:
 	@echo "Check finished. Wrong words can be found in " \
 		"build/spelling/output.txt."
 
-################################################################################
-VENV = env/bin/activate
-PORT = 8001
-# CORE COMMANDS
-install:
-	@echo "... setting up virtualenv"
-	python3.6 -m venv env
-	. $(VENV); pip install -r requirements.txt
-	. $(VENV); $(SPHINXBUILD) . build/html
-	@echo "\n" \
-	      "-------------------------------------------------------------------------------------------------- \n" \
-		    "* watch, build and serve the documentation: make run \n" \
-		    "* check spelling: make spelling \n" \
-		    "\n" \
-				"enchant must be installed in order for pyenchant (and therefore spelling checks) to work. See \n" \
-				"http://docs.django-cms.org/en/latest/contributing/documentation.html#install-the-spelling-software \n" \
-	      "-------------------------------------------------------------------------------------------------- \n" \
-
 run:
 	. $(VENV); sphinx-autobuild $(ALLSPHINXOPTS) build/html --host 0.0.0.0 --port $(PORT)

docs/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 #
 # django cms documentation build configuration file, created by
 # sphinx-quickstart on Tue Sep 15 10:47:03 2009.
@@ -12,6 +11,8 @@
 # All configuration values have a default; values that are commented out serve
 # to show the default.
 
+import cms
+import datetime
 import os
 import sys
 
@@ -39,7 +40,7 @@
     ]
 intersphinx_mapping = {
     'python': ('http://docs.python.org/3/', None),
-    'django': ('https://docs.djangoproject.com/en/1.11/', 'https://docs.djangoproject.com/en/1.11/_objects/'),
+    'django': ('https://docs.djangoproject.com/en/2.2/', 'https://docs.djangoproject.com/en/2.2/_objects/'),
     'classytags': ('http://readthedocs.org/docs/django-classy-tags/en/latest/', None),
     'sekizai': ('http://readthedocs.org/docs/django-sekizai/en/latest/', None),
     'treebeard': ('http://django-treebeard.readthedocs.io/en/latest/', None),
@@ -57,9 +58,10 @@
 # The master toctree document.
 master_doc = 'index'
 
+current_year = datetime.datetime.now().year
 # General information about the project.
 project = u'django cms'
-copyright = u'2009-2017, Divio AG and contributors'
+copyright = u'2009-{}, Divio AG and contributors'.format(current_year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -70,7 +72,6 @@
 path = os.path.split(os.path.dirname(__file__))[0]
 path = os.path.split(path)[0]
 sys.path.insert(0, path)
-import cms
 
 version = cms.__version__
 # The full version, including alpha/beta/rc tags.
@@ -130,9 +131,22 @@
     import divio_docs_theme
     html_theme = 'divio_docs_theme'
     html_theme_path = [divio_docs_theme.get_html_theme_path()]
+    html_theme_options = {
+        'show_cloud_banner': True,
+        'cloud_banner_markup': """
+            <div class="divio-cloud">
+                <span class="divio-cloud-caption">The django CMS Association</span>
+                <p>The django CMS Association is a non-profit organisation that funds and
+                steers the development of django CMS, and nurtures its world-wide
+                community of developers and users.</p>
+                <a class="btn-neutral divio-cloud-btn" target="_blank" href="https://www.django-cms.org/en/about-us/">Join us</a>
+            </div>
+        """,
+    }
 except:
     html_theme = 'default'
 
+
 show_cloud_banner = True
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with

docs/contributing/code.rst

@@ -14,7 +14,7 @@ In a nutshell
 
 Here's what the contribution process looks like in brief:
 
-#. Fork our `GitHub`_ repository, https://github.com/divio/django-cms
+#. Fork our `GitHub`_ repository, https://github.com/django-cms/django-cms
 #. Work locally and push your changes to your repository.
 #. When you feel your code is good enough for inclusion, send us a pull request.
 
@@ -26,7 +26,7 @@ Basic requirements and standards
 ********************************
 
 If you're interested in developing a new feature for the CMS, it is recommended
-that you first discuss it on the `django-cms-developers`_  mailing list so as
+that you first discuss it on the `Discourse forum <https://discourse.django-cms.org>`_ so as
 not to do any work that will not get merged in anyway.
 
 - Code will be reviewed and tested by at least one core developer, preferably
@@ -105,11 +105,9 @@ coverage will only be accepted with a very good reason; bug-fixing patches
 **must** demonstrate the bug with a test to avoid regressions and to check
 that the fix works.
 
-We have an IRC channel, our `django-cms-developers`_ email list,
-and of course the code reviews mechanism on GitHub - do use them.
+We have `a Slack group <https://www.django-cms.org/slack>`_, a `Discourse forum
+<https://discourse.django-cms.org>`_, and of course the code reviews mechanism on GitHub - do use them.
 
-If you don't have an IRC client, you can `join our IRC channel using the KiwiIRC web client
-<https://kiwiirc.com/client/irc.freenode.net/django-cms>`_, which works pretty well.
 
 .. _contributing_frontend:
 
@@ -194,7 +192,7 @@ CMS in external applications, you can only use bundles distributed by CMS, not
 the source modules.
 
 
-.. _fork: https://github.com/divio/django-cms
+.. _fork: https://github.com/django-cms/django-cms
 .. _PEP8: http://www.python.org/dev/peps/pep-0008/
 .. _Aldryn Boilerplate: https://aldryn-boilerplate-bootstrap3.readthedocs.io/en/latest/guidelines/index.html
 .. _django-cms-developers: https://groups.google.com/group/django-cms-developers

docs/contributing/code_of_conduct.rst

@@ -13,9 +13,9 @@ We will not tolerate abusive behaviour or language or any form of harassment.
 
 Individuals whose behaviour is a cause for concern will be give a warning, and
 if necessary will be excluded from participation in official django CMS
-channels (email lists, IRC channels, etc) and events. The `Django Software
-Foundation <http://djangoproject.com/foundation/>`_ will also be informed of
-the issue.
+channels (Slack group, Discourse forum, email lists, IRC channels, etc) and
+events. The `Django Software Foundation
+<http://djangoproject.com/foundation/>`_ will also be informed of the issue.
 
 *****************
 Raising a concern