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

Hugo is a static site renderer - so to get the documentation site presented you need a running Hugo processor. Therefore there is 

* either a Hugo [`.devcontainer`-definition](https://containers.dev/) - just run a devcontainer aware IDE or CLI, e.g. Visual Studio code
* or a Hugo [`Devbox`-definition](https://www.jetify.com/devbox/) - in this case just run a devbox shell

## Local installation of the Hugo documentation system

We describe two possible ways (one with devcontainer, one with devbox) to get the Hugo-documentation system locally running.

For both prepare the following three steps:

1. open a terminal on your local box
2. clone this repo: `git clone https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/website-and-documentation`
3. change to the repo working dir: `cd website-and-documentation`

### Possibility 1: Hugo in a devcontainer

[`devcontainers`](https://containers.dev/) are running containers as virtual systems on your local box. The defintion is in the `.devcontainer` folder.
Thus as preliminary you need a container daemon running, e.g. Docker.

There are several options to create and run the devcontainer - we present here two:

#### Option 1: Run the container triggered by and connected to an IDE, e.g. VS Code

1. open the repo in an [Devcontainer-aware tool/IDE](https://containers.dev/supporting) (e.g. `code .`)
1. start the `devcontainer` (in VSC it's `F1 + Reopen in Devcontainer`)
1. when the container is up & running just open your browser with `http://localhost:1313/`

#### Option 2: Run the container natively

An alternative to get the container image is the [devcontainer CLI](https://github.com/devcontainers/cli), then you can run the devcontainer without VS Code.
Thus as preliminary you need to do the install steps of the devconatiner cli.

1. start the devcontainer by running: `devcontainer up --workspace-folder .`
1. find out the IP address of the devconatiner by using `docker ps` and `docker inspect <id of container>`
1. when the container is up & running just open your browser with `http://<DOCKER IP>:1313/`

### Possibility 2: Hugo in a devbox

[`Devboxes`](https://www.jetify.com/devbox/) are locally isolated environments, managed by the [Nix package manager](https://nix.dev/). So first [prepare the devbox](https://www.jetify.com/docs/devbox/installing_devbox/).

Then

1. ```devbox shell```
1. In the shell: ```hugo serve```


## 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:

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

### Final result in a web browser

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