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).