docs: update docs since TACC/Core-CMS#741 (#196)

* docs: update docs since TACC/Core-CMS#741

* docs: restore debug-project.md

Author: wesleyboar

README.md

@@ -70,7 +70,7 @@ A CMS project is run within [Core CMS]. Also, [Git Submodules] must be pre-insta
 
 Set up a new local CMS instance.
 
-0. Core CMS:
+0. Set up Core CMS to run a local Core CMS Resources:
 
     1. If not already done:
         1. Clone [Core CMS] repository.
@@ -96,31 +96,27 @@ Set up a new local CMS instance.
         ln -s '../taccsite_custom/custom_project_dir/settings_custom.py' 'taccsite_cms/settings_custom.py'
         ```
 
-1. Docker Containers:
+1. Enter the CMS Docker Container:
 
     ```sh
     docker exec -it core_cms /bin/bash
-    # This opens a command prompt within the container.
+    # This opens a command prompt within the container
     ```
 
-2. Django Application:
+2. Update the Django Application:
 
     (Run these commands within the container.)
 
     ```sh
     python manage.py migrate
-    # For projects that install apps
-    # e.g. ECEP installs News/Blog
-    npm ci
-    npm run build:css --project="custom_project_dir"
-    # If output includes
-    # "Input Error: You must pass a valid"
-    # then double check you have the directory
-    # `taccsite_cms/…/static/…/css/src`
+    python manage.py createsuperuser
+    # To use default "Username" and skip "Email address", press Enter at both prompts.
+    # At "Password" prompts, you may use an easy-to-remember password.
     python manage.py collectstatic --no-input
+
     ```
 
-3. Django CMS:
+3. Open Django CMS:
     1. Open http://localhost:8000/.
     2. Verify anything specific to the custom project is present e.g.
         - logo
@@ -132,41 +128,15 @@ Set up a new local CMS instance.
 > A local machine CMS will be empty. It will **not** have content from staging nor production. To have that, follow and adapt instructions to [copy a database](https://confluence.tacc.utexas.edu/x/W4DZDg).
 
 > **Note**
-> A local machine CMS does **not** include **nor** integrate with an instance of [Core Portal]. There are no reliable instructions to do either. **Help welcome.**
+> A local machine CMS does **not** include **nor** integrate with an instance of [Core Portal]. To attempt to do that, follow [How to Use a Custom Docker Compose File](https://github.com/TACC/Core-CMS/wiki/How-to-Use-a-Custom-Docker-Compose-File) and [Locally Develop CMS Portal Docs](https://github.com/TACC/Core-CMS/wiki/Locally-Develop-CMS---Portal---Docs). **Help welcome.**
 
 ## Update Project
 
-To update an existing CMS instance.
-
-### New Major [Core CMS] Version (or v3.12)
-
-Read [Upgrade Project] for developer instructions.
+Follow [Core CMS: Update Project](https://github.com/TACC/Core-CMS/blob/main/README.md#update-project) instructions.
 
-### New Branch (or Minor or Patch [Core CMS] Version)
+## Develop Project
 
-1. If CMS Docker files changed, rebuild Docker Containers:
-
-    ```sh
-    cd custom_project_dir
-    make stop
-    make build
-    make start
-    ```
-
-2. If static assets or database models changed, update the Django Application:
-
-    ```sh
-    docker exec -it core_cms /bin/bash
-    # That opens a command prompt within the container.
-        python manage.py migrate
-        python manage.py collectstatic --no-input
-        # If the project has no new/changed assets,
-        # then expect output of "0 static files […]"
-    ```
-
-## Run Multiple Projects
-
-Read [Multiple Projects](./docs/run-project.md#multiple-projects).
+Follow "via Core CMS Resources" section of [Core CMS: Develop Custom Project](https://github.com/TACC/Core-CMS/blob/main/docs/develop-custom-project.md#via-core-cms-resources).
 
 ## Debug Project
 
@@ -176,6 +146,10 @@ Read [Debug Project](./docs/debug-project.md) for miscellaneous tips.
 
 Follow "Core-CMS-Resources" section of [How To Build & Deploy][Build & Deploy Project].
 
+## Run Multiple Projects
+
+Read [Run Multiple Projects](./docs/run-multiple-projects.md).
+
 ## Port Project
 
 To port a project to [Core CMS Custom], read [Port Project].

docs/debug-project.md

@@ -9,3 +9,16 @@
 
 1. Review content of `/taccsite_custom/custom_project_dir/static/custom_project_dir/css/build`.
 2. Verify that content is also _in the container_ at `/static/custom_project_dir/css/build`.
+
+> **Note**
+> You will never see `/static/*/css/src`, because [this app ignores `src/`][ignore-src-dirs] when [collecting static files](#collect-static-files). This is done so templates can **not** load load source files.
+
+[ignore-src-dirs]: https://github.com/TACC/Core-CMS/blob/7b62db1/taccsite_cms/django/contrib/staticfiles_custom/apps.py
+
+## Restart CMS Server
+
+See [How to Restart the CMS Server](https://github.com/TACC/Core-CMS/wiki/How-to-Restart-the-CMS-Server).
+
+## Build Search Index
+
+See [How to Build Search Index](https://github.com/TACC/Core-CMS/wiki/How-to-Build-Search-Index).

docs/run-project.md docs/run-multiple-projects.md

@@ -1,10 +1,6 @@
-# Run Project
+# Run Multiple Projects
 
-## Individual Projects
-
-No developer instruction beyond those for Core CMS.
-
-## Multiple Projects
+## One at a Time
 
 > **Note**
 > By default, multiple projects can not be run simultaneously.[^1]
@@ -39,13 +35,7 @@ To stop one project, and run another:
     > **Warning**
     > With these instructions, if a project has different apps installed, and especially if you used those apps on your local CMS, you will likely encounter an error. This document can **not** help you solve such an error.[^1]
 
-    ```sh
-    python manage.py migrate
-    npm run build:css --project="custom_project_dir"
-    python manage.py collectstatic --no-input
-    ```
-
-[^1]: If you want to run multiple projects simultaneously, and avoid the Warning for multiple projects, see [Simultaneous Projects](#simultaneous-projects).
+    Follow [Core CMS: Getting Started: Build & Start the Docker Containers](https://github.com/TACC/Core-CMS/blob/main/README.md#build--start-the-docker-containers) instructions.
 
 ## Simultaneous Projects
 
@@ -57,3 +47,9 @@ To run multiple projects simultaneously:
 1. Create another clone of [Core CMS].
 2. Set up the CMS in that clone.
 3. Set up the other project in that CMS.
+
+[^1]: If you want to run multiple projects simultaneously, and avoid the Warning for multiple projects, see [Simultaneous Projects](#simultaneous-projects).
+
+<!-- Link Aliases -->
+
+[Core CMS]: https://github.com/TACC/Core-CMS