feat(example): improve example app, add upgrade doc (#177)

* feat(example): core-cms v3.11.3

* chore: move e-mail settings to same spot

* chore: move all images to /img, no child dirs

* test: remove elasticsearch.yml (core-cms has it)

* chore: set TACC_CORE_STYLES_VERSION = 2

So new projects use v2!

Migrated projects, they need to be checking every setting.

* feat(example): core cms v3.12.0-beta.3

* chore: try to clean up diff

* chore: extra new line (for consistency)

* feat!: install custom app (FAIL)

Breaking Change: Fails with error.

```
django.core.exceptions.ImproperlyConfigured: Cannot import 'custom_example'. Check that 'apps.custom_example.apps.CustomExampleConfig.name' is correct.
```

* fix: upgrade for Core-CMS v3.12 (i.e. Django 3.2)

* feat: new upgrade path to Core-CMS v3.12

* docs(port-project): small improvements

* docs(upgrade-project): add "Rename Project"

And make some small fixes.

* docs(upgrade-project): refactor "Rename Project"

* docs(develop-project): apps are moved

* docs(upgrade-project): drop extra STATICFILES_DIRS

* chore: whtiespace tweak

* refactor(example-cms): undo unnecessary changes

* docs(upgrade-project): add "Move Images"

And make minor fixes.

* docs(upgrade-project): move aliases to bottom

README.md

@@ -14,6 +14,7 @@ Extensions of the [Core CMS] project
 - [Build Project](#build-project)
 - [Deploy Project](#deploy-project)
 - [Port Project](#port-project)
+- [Upgrade Project](#upgrade-project)
 
 ## Related Repositories
 
@@ -161,6 +162,10 @@ Follow "Core-CMS-Custom" section of [How To Build & Deploy][Deploy Project].
 
 To port a project from [Core CMS Resources], read [Port Project].
 
+## Upgrade Project
+
+To upgrade components of an existing project (e.g. [Core CMS]), read [Upgrade Project].
+
 <!-- Link Aliases -->
 
 [Core Portal Deployments]: https://github.com/TACC/Core-Portal-Deployments
@@ -176,6 +181,7 @@ To port a project from [Core CMS Resources], read [Port Project].
 
 [Deploy Project]: https://tacc-main.atlassian.net/wiki/x/2AVv
 [Port Project]: ./docs/port-project.md
+[Upgrade Project]: ./docs/upgrade-project.md
 [Django CMS User Guide]: https://tacc-main.atlassian.net/wiki/x/phdv
 
 [Upgrade Project]: https://github.com/TACC/Core-CMS/blob/main/docs/upgrade-project.md

docs/upgrade-project.md

@@ -0,0 +1,85 @@
+# Upgrade Project
+
+## Table of Contents
+
+- [Core-CMS v3.11 to v3.12](#core-cms-v311-to-v312)
+    1. [Rename Project](#rename-project)
+    2. [Update Settings](#update-settings)
+    3. [Move Images](#move-images)
+
+## [Core CMS] v3.11 to v3.12
+
+### Rename Project
+
+Verify project name is compatible with Django 3.2.
+
+1. If your project directory name has dashes, rename it to use underscores, i.e.
+
+    | | root |
+    | - | - |
+    | from | `custom-project-dir` |
+    | to | `custom_project_dir` |
+
+    | | `taccsite_custom` |
+    | - | - |
+    | from | `taccsite_custom/custom-project-dir` |
+    | to | `taccsite_custom/custom_project_dir` |
+
+    | |`taccsite_cms/static` |
+    | - | - |
+    | from | `taccsite_cms/static/custom-project-dir` |
+    | to | `taccsite_cms/static/custom_project_dir` |
+
+    > **Important**
+    > A valid Python application uses underscores.
+
+2. Rename **all** references to the previous directory names.
+
+3. Identify, support and deprecate old CMS template paths.
+
+    Follow [Port Project: Old CMS Template paths](./port-project.md#old-cms-template-paths).
+
+    > **Important**
+    > Failure to do this can crash an entire page.
+
+4. In `taccsite_cms/custom_app_settings.py`, remove project from `STATICFILES_DIRS`, i.e.
+
+    | | change |
+    | - | - |
+    | from | `STATICFILES_DIRS = ('taccsite_custom/custom_project_dir', ...)` |
+    | to | `STATICFILES_DIRS = (...)` |
+
+    > **Note**
+    > [Core CMS] already defines the `static` directory for each project.
+
+### Update Settings
+
+Remove unnecessary settings.
+
+1. In `taccsite_cms/custom_app_settings.py`, remove apps from `STATICFILES_DIRS`, i.e.
+
+    | | change |
+    | - | - |
+    | from | `STATICFILES_DIRS = ('apps/custom_example', ...)` |
+    | to | `STATICFILES_DIRS = (...)` |
+
+    > **Note**
+    > Django automatically identifies the `static` directory for each app.
+
+### Move Images
+
+Verify project name is compatible with Django 3.2.
+
+1. Remove any subdirectories of your project's static `img` directory, i.e.
+
+    | | root |
+    | - | - |
+    | from | `taccsite_custom/static/custom_project_dir/img/*/...` |
+    | to | `taccsite_custom/static/custom_project_dir/img/...` |
+
+2. Rename **all** references to the previous image paths e.g.
+    - in `settings_custom.py`
+
+<!-- Link Aliases -->
+
+[Core CMS]: https://github.com/TACC/Core-CMS

example_cms/docker-compose.dev.yml

@@ -40,7 +40,6 @@ services:
       - ES_HEAP_SIZE:1g
       - discovery.type=single-node
     volumes:
-      - ./elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml
       - core_cms_es_data:/usr/share/elasticsearch/data
     container_name: core_cms_elasticsearch
     ports:

example_cms/src/apps/example_app/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class ExampleAppConfig(AppConfig):
+    name = 'apps.example_app'

example_cms/src/apps/example_app/static/example_app/css/example_app.css

@@ -0,0 +1,3 @@
+h1 {
+    color: green;
+}

example_cms/src/apps/example_app/templates/example_app/index.html

@@ -0,0 +1,13 @@
+{% extends "base.html" %}
+{% load static sekizai_tags %}
+
+{% block content %}
+
+{% addtoblock "css" %}
+<link rel="stylesheet" type="text/css" href="{% static 'example_app/css/example_app.css' %}">
+{% endaddtoblock %}
+
+<h1>Example App</h1>
+<p>Example application content.</p>
+
+{% endblock %}

example_cms/src/apps/custom_example/urls.py → example_cms/src/apps/example_app/urls.py

@@ -1,7 +1,8 @@
 from django.urls import re_path
 from .views import AddedView
 
-app_name = 'custom_example'
+
+app_name = 'example_app'
 urlpatterns = [
     re_path('', AddedView, name='index'),
 ]

example_cms/src/apps/custom_example/views.py → example_cms/src/apps/example_app/views.py

@@ -5,5 +5,5 @@
 
 
 def AddedView(request):
-    template = loader.get_template('custom_example/custom_example.html')
+    template = loader.get_template('example_app/index.html')
     return HttpResponse(template.render({}, request))

example_cms/src/taccsite_cms/custom_app_settings.py

@@ -1,3 +1,3 @@
-CUSTOM_APPS = []
+CUSTOM_APPS = ['apps.example_app']
 CUSTOM_MIDDLEWARE = []
 STATICFILES_DIRS = ()

example_cms/src/taccsite_cms/settings_custom.py

@@ -29,7 +29,7 @@
 #
 # _CUSTOM_BRANDING = [
 #     "example",
-#     "example_cms/img/org_logos/example-logo.png",
+#     "example_cms/img/some-logo.png",
 #     "",
 #     "https://example.com",
 #     "_blank",
@@ -46,7 +46,7 @@
 
 LOGO =  [
     "example",
-    "example_cms/img/org_logos/portal.png",
+    "example_cms/img/portal.png",
     "",
     "/",
     "_self",
@@ -55,10 +55,20 @@
     "True"
 ]
 
+FAVICON = {
+    "img_file_src": "example_cms/img/favicon.ico"
+}
+
 ########################
 # TACC: PORTAL
 ########################
 
 # INCLUDES_CORE_PORTAL = False
 # INCLUDES_PORTAL_NAV = False
 # INCLUDES_SEARCH_BAR = False
+
+########################
+# TACC: CORE STYLES
+########################
+
+TACC_CORE_STYLES_VERSION = 2

example_cms/src/taccsite_cms/urls_custom.py

@@ -1,3 +1,5 @@
 from django.urls import path, include
 
-custom_urls = []
+custom_urls = [
+    path('example_app/', include('apps.example_app.urls', namespace='example_app')),
+]