website-and-documentation/README.md

# IPCEICIS-DeveloperFramework Documentation

This repo contains business and architectural design and documentation of the DeveloperFramework subproject of IPCEI-CIS.

## How to read and contribute to this documentation locally

The documentation is done in [Hugo-format](https://gohugo.io).

The repo contains a [Hugo `.devcontainer`-defintion](https://containers.dev/) so that you just have to run locally an IDE which is devcontainer aware, e.g. Visual Studio code.

### Installation

To get a locally running documentation editing and presentation environment, follow these steps:

1. open a terminal on your local box
2. clone this repo: `git clone https://bitbucket.telekom-mms.com/scm/ipceicis/ipceicis-developerframework.git `
3. change to the repo working dir: `cd ipceicis-developerframework`
4. open the repo in an [Devcontainer-aware tool/IDE](https://containers.dev/supporting) (e.g. `code .`)
5. start the `devcontainer` (in VSC it's `F1 + Reopen in Devcontainer`)
6. when the container is up & running just open your browser with `http://localhost:1313/`

If you want to run the devcontainer without VS Code, you can use npm to run it inside a docker container:

1. install Node.js (>= Version 14), npm and the docker engine
2. install the devcontainer cli: `npm install -g @devcontainers/cli`
3. change into the folder of this repo
4. start the devcontainer by running: `devcontainer up --workspace-folder .`
5. find out the IP address of the devconatiner by using `docker ps` and `docker inspect <id of container>`
6. when the container is up & running just open your browser with `http://<DOCKER IP>:1313/`

### Editing

#### Documentation language

The documentation is done in [Docsy-Theme](https://www.docsy.dev/).

So for editing content just goto the `content`-folder and edit content arrording to the [Docsy documentation](https://www.docsy.dev/docs/adding-content/)

### Commiting

After having finished a unit of work commit and push.

## Annex

### Installation steps illustrated

When you run the above installation, the outputs could typically look like this:

#### Steps 4/5 in Visual Studio Code

##### Reopen in Container

![vsc-f1](./assets/images/vsc-f1.png)

##### Hugo server is running and (typically) listens to localhost:1313

After some installation time you have:

![vsc-hugo](./assets/images/vsc-hugo.png)

#### Steps 6 in a web browser

![browser](./assets/images/browser.png)