From 556b3ea64cf321a597b472c624acc7bd391dd233 Mon Sep 17 00:00:00 2001
From: Wesley B <62723358+wesleyboar@users.noreply.github.com>
Date: Mon, 26 Jun 2023 15:09:20 -0500
Subject: [PATCH] docs: project readme polish (#174)
---
README.md | 8 +++---
apcd-cms/README.md | 8 ++++--
demdata_cms/README.md | 8 ++++--
docs/develop-project.md | 61 +++++++++++++++++++++++++++++++++++++++++
docs/run-project.md | 2 ++
example_cms/README.md | 6 ++--
matcssi_cms/README.md | 8 ++++--
7 files changed, 85 insertions(+), 16 deletions(-)
create mode 100644 docs/develop-project.md
diff --git a/README.md b/README.md
index a1b0b265..985fa80e 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ Extensions of the [Core CMS] project
- [Start Project](#start-project)
- [Update Project](#update-project)
- [Run Project](#run-project)
-- [Develop Project](#develop-project)
+- [Develop Project](./docs/develop-project.md)
- [Build Project](#build-project)
- [Deploy Project](https://confluence.tacc.utexas.edu/x/Lo99E) (at "Core-CMS-Custom" section)
- [Port Project](./docs/port-project.md)
@@ -131,10 +131,10 @@ To run multiple projects, first read [Multiple Projects](./docs/run-project.md#m
## Develop Project
-### Running a Custom App
+To develop a new project, read [Develop Project](./docs/develop-project.md) e.g.
-- Update `custom_app_settings.py` with relevant content from [TACC/Core-CMS:`/taccsite_cms/custom_app_settings.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/custom_app_settings.example.py).
-- Update `urls_custom.py` with relevant content from [TACC/Core-CMS:`/taccsite_cms/urls_custom.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/urls_custom.example.py).
+- [Customize Project](./docs/develop-project.md#customize-project)
+- [Create a Custom App](./docs/develop-project.md#create-a-custom-app)
## Build Project
diff --git a/apcd-cms/README.md b/apcd-cms/README.md
index 82b8a8ab..34f76652 100644
--- a/apcd-cms/README.md
+++ b/apcd-cms/README.md
@@ -1,7 +1,9 @@
-# apcd-cms
+# APCD
+
+https://democratizingdata.ai/
An extension of the [Core CMS](https://github.com/TACC/Core-CMS) project
-## Basic Set Up
+## Basics
-See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom).
+See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom#readme).
diff --git a/demdata_cms/README.md b/demdata_cms/README.md
index 82b8a8ab..baff71ba 100644
--- a/demdata_cms/README.md
+++ b/demdata_cms/README.md
@@ -1,7 +1,9 @@
-# apcd-cms
+# Democratizing Data
+
+https://democratizingdata.ai/
An extension of the [Core CMS](https://github.com/TACC/Core-CMS) project
-## Basic Set Up
+## Basics
-See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom).
+See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom#readme).
diff --git a/docs/develop-project.md b/docs/develop-project.md
new file mode 100644
index 00000000..bb12af22
--- /dev/null
+++ b/docs/develop-project.md
@@ -0,0 +1,61 @@
+# Develop Project
+
+## Table of Contents
+
+- [Remove Excess Content](#remove-excess-content)
+- [Customize Project](#customize-project)
+- [Create a Custom App](#create-a-custom-app)
+- [Change All Projects](#change-all-projects)
+
+## Create a New Project
+
+1. Clone [example_cms](../example_cms).
+2. Name the directory as WMA Infrastructure team defines e.g. `demdata_cms`.
+3. [Remove Excess Content](#remove-excess-content)
+4. [Customize Project](#customize-project)
+5. Perform instructions in other pertinent sections.
+
+## Remove Excess Content
+
+> **Note**
+> [Core CMS] supports standard TACC apps, URLs, and static asset directories. Consider its capabilities before creating something new.
+
+| If Project Does Not Need | Then Delete |
+| - | - |
+| additional apps | `apps/` |
+| URLs for custom apps | `urls_custom.py` |
+| custom code | `custom_app_settings.py` |
+
+## Customize Project
+
+Edit `settings_custom.py`. To know what settings are available, see [Core-CMS `settings.py`](https://github.com/TACC/Core-CMS/blob/main/taccsite_cms/settings.py).
+
+The settings usually edited are `LOGO` and `..._BRANDING`.
+
+## Create a Custom App
+
+- Update `custom_app_settings.py` with pertinent content from [TACC/Core-CMS:`/taccsite_cms/custom_app_settings.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/custom_app_settings.example.py).
+- Update `urls_custom.py` with pertinent content from [TACC/Core-CMS:`/taccsite_cms/urls_custom.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/urls_custom.example.py).
+
+## Change All Projects
+
+If there is a change that should be made in all CMS projects, consider whether it can be done in a more appropriate repository.
+
+| Type of Change | Repository |
+| - | - |
+| CMS feature / default setting | [Core CMS] |
+| styles specific to CMS[^1] | [Core CMS] |
+| [TACC UI Patterns] [^2] | [Core Styles] |
+| [Core Portal] |
+
+[^1]: These are not always obviously distinct from [Core Styles]. Examples may be the News plugin, the Image Gallery, forms, and any "Core CMS" patterns in [TACC UI Patterns].
+
+[^2]: There may be styles from [Core Styles] that are not documented in [TACC UI Patterns].
+
+
+
+[Core CMS]: https://github.com/TACC/Core-CMS
+[Core Portal]: https://github.com/TACC/Core-Portal
+[Core Styles]: https://github.com/TACC/Core-Styles
+
+[TACC UI Patterns]: https://tacc.utexas.edu/static/ui/
diff --git a/docs/run-project.md b/docs/run-project.md
index 5b7a2032..a0a12309 100644
--- a/docs/run-project.md
+++ b/docs/run-project.md
@@ -48,4 +48,6 @@ To run multiple projects simultaneously:
[^2]: Advanced adaptation of these instructions may support retaining database access, et cetera.
+
+
[copy a database]: https://confluence.tacc.utexas.edu/pages/viewpage.action?pageId=249135195
diff --git a/example_cms/README.md b/example_cms/README.md
index 9c63dc74..dd1f815a 100644
--- a/example_cms/README.md
+++ b/example_cms/README.md
@@ -1,7 +1,7 @@
-# matcssi_cms
+# Example
An extension of the [Core CMS](https://github.com/TACC/Core-CMS) project
-## Basic Set Up
+## Basics
-See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom).
+See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom#readme).
diff --git a/matcssi_cms/README.md b/matcssi_cms/README.md
index 9c63dc74..bb535159 100644
--- a/matcssi_cms/README.md
+++ b/matcssi_cms/README.md
@@ -1,7 +1,9 @@
-# matcssi_cms
+# MatCSSI
+
+https://matcssi.tacc.utexas.edu/
An extension of the [Core CMS](https://github.com/TACC/Core-CMS) project
-## Basic Set Up
+## Basics
-See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom).
+See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom#readme).