refactor: Use title case in documentation

DSD-DBS · Oct 25, 2023 · d89eda3 · d89eda3
1 parent d47d71f
commit d89eda3
Show file tree

Hide file tree

Showing 51 changed files with 138 additions and 112 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -73,7 +73,6 @@ repos:
     hooks:
       - id: prettier
         types_or: [ts, css, html, markdown]
-        files: "^frontend"
         additional_dependencies:
           - "prettier@^3.0.3"
           - "prettier-plugin-tailwindcss@^0.5.5"

diff --git a/README.md b/README.md
@@ -52,9 +52,9 @@ In addition, we have integrated commercial products:
   - Automatic license injection
   - Access to licenses is self-managed by project leads
 
-## Getting started
+## Getting Started
 
-### Running locally with k3d
+### Running Locally with k3d
 
 #### Prerequisites
 
@@ -78,7 +78,7 @@ When you have all that installed you can do the following:
 git clone --recurse-submodules https://github.com/DSD-DBS/capella-collab-manager.git
 cd capella-collab-manager
 
-# Create a local k3d cluster
+# Create a Local k3d Cluster
 make create-cluster
 ```
 
@@ -136,7 +136,7 @@ make delete-cluster
 k3d registry delete k3d-myregistry.localhost
 ```
 
-#### Starting a session
+#### Starting a Session
 
 Once the cluster is installed and all services are running (`kubectl get pods`), you can
 get started. Follow our [Getting started guide](docs/getting_started/getting_started.md) and be up and
@@ -146,7 +146,7 @@ running in a few minutes.
 
 You can find the installation guide for the deployment in the [general documentation](https://capella-collaboration-manager.readthedocs.io/en/latest/installation/).
 
-## How it works
+## How it Works
 
 The Capella Collaboration Manager consists of a couple of components:
 

diff --git a/docs/docs/admin/ci-templates/gitlab/image-builder.md b/docs/docs/admin/ci-templates/gitlab/image-builder.md
@@ -3,7 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Image builder (Gitlab CI/CD)
+# Image Builder (Gitlab CI/CD)
 
 The image builder template builds the following images and pushes them to any
 Docker registry:
@@ -50,7 +50,7 @@ please refer to the
 [image-builder](https://github.com/DSD-DBS/capella-collab-manager/blob/main/ci-templates/gitlab/image-builder.yml)
 Gitlab template.
 
-### Docker SOPS file
+### Docker SOPS File
 
 We make use of [Mozilla SOPS](https://github.com/mozilla/sops) files to store
 secrets used in the image builder template. Therefore you need to have a

diff --git a/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md b/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md
@@ -31,7 +31,7 @@ In addition you can adjust the following variables when running a pipeline:
 - `REVISION`: The revision of the capella collab manager repository you want to
   use
 
-### Docker and Kubernetes sops files
+### Docker and Kubernetes SOPS Files
 
 For the `k8s-deploy.yml` you need to have some secret sops files in place.
 First of all, you need a `secret.docker.json` file as described
@@ -57,7 +57,7 @@ the `_unencrypted` suffix in the variable names).
 Please delete the plain text files containing secrets directly after encrypting
 them.
 
-## Gitlab repository tree
+## Gitlab Repository Tree
 
 The tree inside of your Gitlab repository should look like:
 

diff --git a/docs/docs/admin/getting_started/getting_started.md b/docs/docs/admin/getting_started/getting_started.md
@@ -3,7 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Getting started
+# Getting Started
 
 This guide describes the steps to get started with the Capella Collaboration
 Manager.
@@ -40,7 +40,7 @@ workspace will be shown in your browser.
 
 ![Capella welcome screen](img/collab-step-5.png)
 
-## What's next
+## What's Next
 
 This introduction only scratches the surface of what's possible with the
 Collaboration Manager.

diff --git a/docs/docs/admin/installation.md b/docs/docs/admin/installation.md
@@ -14,7 +14,7 @@ During development, we also took into account that the application can be
 installed in highly restricted environments. An internet connection is not
 necessarily required.
 
-## Step 1: Set up a Kubernetes cluster
+## Step 1: Set up a Kubernetes Cluster
 
 Kubernetes allows us to make operations as simple as possible later on. Updates
 can be fully automated. In addition, Kubernetes allows us to ensure a secure
@@ -92,7 +92,7 @@ future.
 
     We are constantly working on expanding our documentation. This installation method is currently not documented. If it is relevant, please feel free to contact us at [email protected]  or open an issue in this repository.
 
-## Step 2: Validate the available resources
+## Step 2: Validate the Available Resources
 
 The minimum required resources are 3
 [Kubernetes CPU cores](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu)
@@ -104,7 +104,7 @@ Each session requires a minimum of 0.4 Kubernetes CPU cores and 1.6Gi of
 memory. A session can scale up until it reaches 2 Kubernetes CPU cores and 6Gi
 of memory.
 
-## Step 3: Set up the required namespaces (optional)
+## Step 3: Set up the Required Namespaces (Optional)
 
 The Collaboration Manager requires two different namespaces. For security and
 overview reasons, they are separated:
@@ -150,7 +150,7 @@ Verify that `helm` is working by executing the command:
 helm version
 ```
 
-## Step 5: Clone the Github repository
+## Step 5: Clone the Github Repository
 
 Navigate to a persistent location on your server, e.g. `/opt`. Then clone the
 Github repository by running:
@@ -159,7 +159,7 @@ Github repository by running:
 git clone https://github.com/DSD-DBS/capella-collab-manager.git
 ```
 
-## Step 6: Configure the environment / Create the `values.yaml`
+## Step 6: Configure the Environment / Create the `values.yaml`
 
 Copy the
 [`values.yaml`](https://github.com/DSD-DBS/capella-collab-manager/blob/main/helm/values.yaml)
@@ -175,7 +175,7 @@ chmod 600 values.yaml
 
 Adjust all values according to your needs.
 
-## Step 7: Install the application in the cluster
+## Step 7: Install the Application in the Cluster
 
 Run the following commands in the root directory of the repository:
 
@@ -188,7 +188,7 @@ helm upgrade --install \
     ./helm
 ```
 
-## Step 8: Initialize the Guacamole database
+## Step 8: Initialize the Guacamole Database
 
 The Guacamole database is not initialized automatically. Run the following
 command to initialize the PostgreSQL database:
@@ -213,7 +213,7 @@ have to change it to a more secure password:
    works.
 1. Update the key `guacamole.password` in the `values.yaml` and repeat step 7.
 
-## Step 9: Check the application status
+## Step 9: Check the Application Status
 
 Run `kubectl get pods` to see the status of all components. Once all containers
 are running, verify the installation state by running:
@@ -230,7 +230,7 @@ It should return the following JSON:
 
 If a value is false, check the backend logs for more information.
 
-## Step 10: Add TeamForCapella support
+## Step 10: Add TeamForCapella Support
 
 <!-- prettier-ignore -->
 !!! info "TeamForCapella server required"

diff --git a/docs/docs/development/backend/authentication.md b/docs/docs/development/backend/authentication.md
@@ -3,12 +3,15 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-## Authentication via personal access token (requires a running frontend)
+## Authentication via Personal Access Token (Requires a Running Frontend)
 
 Find more information about authentication with personal access tokens in the
 user documentation: [Authentication](../../user/tokens.md)
 
-## Authentication without application frontend
+As soon as you have a PAT (Personal Access Token) you can authenticate without
+the application frontend.
+
+## Authentication without Application Frontend
 
 Request the `auth_url`
 

diff --git a/docs/docs/development/backend/code-style.md b/docs/docs/development/backend/code-style.md
@@ -100,7 +100,7 @@ Python code. The key differences are:
     `from .. import y as z` for one level above. For all other imports beyond
     this level, use the full path as described in 3.
 
-### Naming conventions
+### Naming Conventions
 
 - All SQLAlchemy models should have `Database` as a prefix, e.g.,
   `DatabaseProject` or `DatabaseUser`.

diff --git a/docs/docs/development/backend/database-migration.md b/docs/docs/development/backend/database-migration.md
@@ -3,7 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Create database migrations scripts
+# Create Database Migration Scripts
 
 To create an upgrade script automatically (this will compare the current
 database state with the models):

diff --git a/docs/docs/development/backend/exception.md b/docs/docs/development/backend/exception.md
@@ -3,7 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Exception handling
+# Exception Handling
 
 Various errors can occur in the backend,
 which must be made understandable to the end user and the developers

diff --git a/docs/docs/development/backend/extensions.md b/docs/docs/development/backend/extensions.md
@@ -21,7 +21,7 @@ extension
 
 The different components are explained in the following section.
 
-## Extension modules
+## Extension Modules
 
 ### `__init__.py`
 

diff --git a/docs/docs/development/docs.md b/docs/docs/development/docs.md
@@ -0,0 +1,23 @@
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB Netz AG and the capella-collab-manager contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# Documentation
+
+Write documentation if necessary so that developer, administrators and users
+have an easily accessible way of learning about the collaboration manager.
+
+## Setup and Serve the Documentation
+
+Navigate to the `docs` folder. With the commands `make install` and
+`make serve` you can build the documentation and find it served under
+`http://127.0.0.1:8081/`. Here you can try your newly written documentation or
+search for something yourself.
+
+## Titles
+
+When writing the documentation we are using title case in the
+[`Chicago Manual of Style` style](https://en.wikipedia.org/wiki/Title_case#Chicago_Manual_of_Style).
+In addition personal names/ names of packages are written according to their
+documentation.
diff --git a/docs/docs/development/frontend/code-style.md b/docs/docs/development/frontend/code-style.md
@@ -7,12 +7,12 @@
 
 ### Crud Functions
 
-#### Creating resource
+#### Creating Resource
 
 For creating a resource one should use `create` as a prefix followed by the
 resource one wants to create (e.g., `createProject(...): Observable<Project>`)
 
-#### Retriving resources
+#### Retriving Resources
 
 In general, one should use `get` as prefix for a function that retrieves and
 returns resources. In case, one wants to get a list of alls resources use

diff --git a/docs/docs/development/frontend/customize.md b/docs/docs/development/frontend/customize.md
@@ -3,7 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Customize the frontend
+# Customize the Frontend
 
 You can customize the frontend by using a custom theme and a custom favicon:
 

diff --git a/docs/docs/development/frontend/routes.md b/docs/docs/development/frontend/routes.md
@@ -3,7 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Frontend routes
+# Frontend Routes
 
 For consistency, we have a strict structure for our frontend route URIs.
 The structure is based on REST, but not completely the same due to the limitations of the unavailable request methods.

diff --git a/docs/docs/development/frontend/testing.md b/docs/docs/development/frontend/testing.md
@@ -11,22 +11,22 @@ our team does not require frontend tests for every component or service.
 Please ensure that ".spec" files are only included if they have active tests.
 Before writing tests, consider the overhead and weigh it against the potential benefits.
 
-## Unit & Integration testing
+## Unit & Integration Testing
 
 ### Technologies
 
 - We use [Jasmine] as testing framework
 - [Karma] is used as test runner
 - We use [istanbul] to measure and visualize the code coverage
 
-### Additional sources
+### Additional Sources
 
 - [Official angular testing guide]
 - Recommended: [Detailed angular testing guide]
 
 ### General
 
-#### Robust component tests
+#### Robust Component Tests
 
 When testing components, we must query the elements needed for the test.
 To ensure that even if the element type or attributes changes, the element
@@ -39,14 +39,14 @@ where the prefix usually describes the general contex (e.g., whether it is
 an input, button, textfield, etc.) and the following description specifies the
 usage of it (e.g., createProject).
 
-#### Element helper functions
+#### Element Helper Functions
 
 Usually testing components consists of querying elements, applying changes
 to them, triggering events on them, and then comparing the results with the
 expected results. To reduce repetition and increase readability, one should
 use existing helper functions or create new ones if none exist.
 
-### Executing tests
+### Executing Tests
 
 To execute the integration tests, one needs to run `make test`. However, in some
 cases it is not possible to correctly set the `CHROME_BIN` that is needed to generate
@@ -68,13 +68,13 @@ and line coverage) are output to the console. To also see what exactly is
 covered and what is missing, one can open the `index.html` file in the
 `/frontend/test-results/istanbul-coverage` folder.
 
-## End-to-End testing
+## End-to-End Testing
 
 ### Technologies
 
 - We use [playwright] for E2E testing
 
-### Test generation
+### Test Generation
 
 Playwright supports the generation of E2E tests by interacting
 with the frontend and recording each action and input. This can be started
@@ -86,7 +86,7 @@ one should only use the resulting test as a base and adjust it accordingly.
 For example, check selectors and adjust them to make them more robust,
 or add more expectations as needed.
 
-### Executing tests
+### Executing Tests
 
 To run the E2E tests, one must first make sure that a backend is running.
 If that is the case, one can run `npx playwright test` to start

diff --git a/docs/docs/development/index.md b/docs/docs/development/index.md
@@ -15,7 +15,7 @@ go ahead and
 to contribute code. In order to reduce the burden on our maintainers, please
 make sure that your code follows our style guidelines.
 
-## Setup of a local Development Environment
+## Setup of a Local Development Environment
 
 In addition to the
 [local k8s deployment](https://github.com/DSD-DBS/capella-collab-manager#running-locally-with-k3d),
@@ -31,7 +31,7 @@ reloading of the frontend and backend.
 - `npm` package manager
 - [`Angular CLI`](https://angular.io/cli#installing-angular-cli)
 
-### Backend configuration
+### Backend Configuration
 
 The backend uses various configuration settings. You can find them in the
 `config` directory. Please copy the file `config_template.yaml` to
@@ -43,7 +43,7 @@ application deployed, then no configuration values need to be adjusted.
 _Hint_: You can run `python -m capellacollab.config.diff` after each update to
 check if your config is up to date.
 
-### Get started
+### Getting Started
 
 To get started, run the following command in the root of the repository for the
 initial setup (only required once):
@@ -67,7 +67,7 @@ If everything went well, the frontend and backend should be running now:
 - [Backend API documentation](http://localhost:8000/docs)
 - [Capella Collaboration Manager Documentation](http://localhost:8081)
 
-## General notes
+## General Notes
 
 ### REST APIs