Add initial content

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Docs
+
+on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    name: docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.11"
+          cache: 'pip'
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - run: python -m pip install -r user-guide/requirements.txt
+      - run: codespell -w user-guide
+      - name: Build docs
+        run: |
+          cd user-guide
+          sphinx-build -b dirhtml -n -d build/doctrees  source build/dirhtml

.gitignore

@@ -0,0 +1,2 @@
+/user-guide/env/
+/user-guide/build/

user-guide/Makefile

@@ -0,0 +1,126 @@
+# Makefile for Sphinx documentation
+# You can set these variables from the command line.
+
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+VENV = env/bin/activate
+PORT = 8001
+SOURCEDIR	  = source
+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) $(SOURCEDIR)
+
+# 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"
+	@echo "  run       to build the docs, watch for changes, and serve them at http://0.0.0.0:8001"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  pickle    to make pickle files"
+	@echo "  json      to make JSON files"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  qthelp    to make HTML files and a qthelp project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+	@echo "  spelling  to check for typos in documentation"
+
+
+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
+	@echo
+	@echo "Build finished. The HTML pages are in build/dirhtml."
+
+pickle:
+	. $(VENV); $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	. $(VENV); $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	. $(VENV); $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in build/htmlhelp."
+
+qthelp:
+	. $(VENV); $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in build/qthelp, like this:"
+	@echo "# qcollectiongenerator build/qthelp/FeinCMS.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile build/qthelp/FeinCMS.qhc"
+
+latex:
+	. $(VENV); $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	. $(VENV); $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
+	@echo
+	@echo "The overview file is in build/changes."
+
+linkcheck:
+	. $(VENV); $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in build/linkcheck/output.txt."
+
+doctest:
+	. $(VENV); $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) build/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in build/doctest/output.txt."
+
+spelling:
+	. $(VENV); $(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) build/spelling
+	@echo
+	@echo "Check finished. Wrong words can be found in " \
+		"build/spelling/output.txt."
+
+run:
+	. $(VENV); sphinx-autobuild $(ALLSPHINXOPTS) build/html --host 0.0.0.0 --port $(PORT)
+
+text:
+	. $(VENV); $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) build/text
+	@echo
+	@echo "Build finished. The HTML pages are in build/text."
+

user-guide/requirements.in

@@ -0,0 +1,15 @@
+MarkupSafe
+Pygments
+furo
+Sphinx>=4.2.0
+sphinx-copybutton
+sphinxext-opengraph
+sphinxcontrib-spelling
+pyenchant>3
+sphinx-autobuild
+datetime
+coverage
+django~=4.2
+git+https://github.com/django-cms/django-cms@release/4.1.x
+codespell
+pip-tools

user-guide/requirements.txt

@@ -0,0 +1,146 @@
+#
+# This file is autogenerated by pip-compile with python 3.10
+# To update, run:
+#
+#    pip-compile
+#
+alabaster==0.7.12
+    # via sphinx
+asgiref==3.5.2
+    # via django
+babel==2.11.0
+    # via sphinx
+beautifulsoup4==4.11.1
+    # via furo
+build==0.9.0
+    # via pip-tools
+certifi==2022.12.7
+    # via requests
+charset-normalizer==2.1.1
+    # via requests
+click==8.1.3
+    # via pip-tools
+codespell==2.2.2
+    # via -r requirements.in
+colorama==0.4.6
+    # via sphinx-autobuild
+coverage==6.5.0
+    # via -r requirements.in
+datetime==4.7
+    # via -r requirements.in
+django==3.2.16
+    # via
+    #   -r requirements.in
+    #   django-classy-tags
+    #   django-cms
+    #   django-formtools
+    #   django-sekizai
+    #   django-treebeard
+django-classy-tags==3.0.1
+    # via
+    #   django-cms
+    #   django-sekizai
+django-cms @ git+https://github.com/django-cms/django-cms@develop-4
+    # via -r requirements.in
+django-formtools==2.4
+    # via django-cms
+django-sekizai==3.0.1
+    # via django-cms
+django-treebeard==4.5.1
+    # via django-cms
+djangocms-admin-style==3.2.0
+    # via django-cms
+docutils==0.19
+    # via sphinx
+furo==2022.12.7
+    # via -r requirements.in
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via sphinx
+livereload==2.6.3
+    # via sphinx-autobuild
+markupsafe==2.1.1
+    # via
+    #   -r requirements.in
+    #   jinja2
+packaging==21.3
+    # via
+    #   build
+    #   django-cms
+    #   sphinx
+pep517==0.13.0
+    # via build
+pip-tools==6.9.0
+    # via -r requirements.in
+pyenchant==3.2.2
+    # via
+    #   -r requirements.in
+    #   sphinxcontrib-spelling
+pygments==2.13.0
+    # via
+    #   -r requirements.in
+    #   furo
+    #   sphinx
+pyparsing==3.0.9
+    # via packaging
+pytz==2022.6
+    # via
+    #   babel
+    #   datetime
+    #   django
+requests==2.28.1
+    # via sphinx
+six==1.16.0
+    # via livereload
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.3.2.post1
+    # via beautifulsoup4
+sphinx==5.3.0
+    # via
+    #   -r requirements.in
+    #   furo
+    #   sphinx-autobuild
+    #   sphinx-basic-ng
+    #   sphinx-copybutton
+    #   sphinxcontrib-spelling
+    #   sphinxext-opengraph
+sphinx-autobuild==2021.3.14
+    # via -r requirements.in
+sphinx-basic-ng==1.0.0b1
+    # via furo
+sphinx-copybutton==0.5.1
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+sphinxcontrib-spelling==7.6.2
+    # via -r requirements.in
+sphinxext-opengraph==0.7.5
+    # via -r requirements.in
+sqlparse==0.4.3
+    # via django
+tornado==6.2
+    # via livereload
+urllib3==1.26.12
+    # via requests
+wheel==0.38.3
+    # via pip-tools
+zope-interface==5.5.1
+    # via datetime
+
+# The following packages are considered to be unsafe in a requirements file:
+# pip
+# setuptools

user-guide/source/_ext/djangocms.py

@@ -0,0 +1,11 @@
+def setup(app):
+    app.add_crossref_type(
+        directivename = "setting",
+        rolename      = "setting",
+        indextemplate = "pair: %s; setting",
+    )
+    app.add_crossref_type(
+        directivename = "templatetag",
+        rolename      = "ttag",
+        indextemplate = "pair: %s; template tag"
+    )

user-guide/source/alias-note.rst

@@ -0,0 +1,3 @@
+.. note::
+
+  This section only applies to installations such as the django-cms-quickstart project which use the djangocms-alias package.