Move user guide to quickstart

django-cms · Dec 8, 2023 · 7bf3d72 · 7bf3d72
1 parent 8fe765f
commit 7bf3d72
Show file tree

Hide file tree

Showing 87 changed files with 2,129 additions and 5 deletions.
diff --git a/.env-local b/.env-local
@@ -1,5 +0,0 @@
-DATABASE_URL=postgres://postgres:password@database_default:5432/db
-DEFAULT_STORAGE_DSN=file:///data/media/?url=%2Fmedia%2F
-DEBUG=True
-DOMAIN_ALIASES="localhost, 127.0.0.1"
-SECURE_SSL_REDIRECT=False

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,34 @@
+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 *.rst
+      - run: codespell -w docs
+      - name: Build docs
+        run: |
+          cd user-guide
+          sphinx-build -b dirhtml -n -d build/doctrees  source build/dirhtml
diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,5 @@ db.sqlite3
 
 .idea/
 .env
+/user-guide/env/
+/user-guide/build/
diff --git a/backend/templates/base2.html b/backend/templates/base2.html
@@ -0,0 +1,34 @@
+<!DOCTYPE html>{% load cms_tags menu_tags sekizai_tags static i18n %}{% spaceless %}
+    <html lang="{{ LANGUAGE_CODE }}">
+        <head>
+            <meta charset="utf-8"/>
+            <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
+            <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"/>
+            {% block meta %}
+                <meta name="description" content="{% page_attribute meta_description %}"/>
+                <meta property="og:type" content="website"/>
+                <meta property="og:title" content="{% page_attribute "page_title" %}"/>
+                <meta property="og:description" content="{% page_attribute meta_description %}"/>
+            {% endblock meta %}
+            {% block canonical_url %}
+                <link rel="canonical" href="{{ request.build_absolute_uri }}"/>
+                <meta property="og:url" content="{{ request.build_absolute_uri }}"/>
+            {% endblock canonical_url %}
+            {% block fb_meta %}{% endblock fb_meta %}
+            <title>{% block title %}{% page_attribute "page_title" %}{% endblock %}</title>
+            {% block base_css %}{% endblock %}
+{% endspaceless %}{% render_block 'css' %}{% spaceless %}
+    {% block page_head %}{% endblock %}
+    </head>
+    <body {% block body_attrs %}{% endblock %}>
+{% endspaceless %}{% cms_toolbar %}{% spaceless %}
+    {% block navbar %}{% endblock %}
+    {% block content %}
+        {% placeholder "Content" %}
+    {% endblock content %}
+    {% block base_js %}{% endblock %}
+{% endspaceless %}{% render_block 'js' %}{% spaceless %}
+    {% block end_js %}{% endblock %}
+    {% block bottom_css %}{% endblock %}
+    </body>
+  </html>{% endspaceless %}
diff --git a/user-guide/Makefile b/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."
+
diff --git a/user-guide/requirements.in b/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
diff --git a/user-guide/requirements.txt b/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
diff --git a/user-guide/source/_ext/djangocms.py b/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"
+    )
diff --git a/user-guide/source/alias-note.rst b/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.