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.

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 - just run a devcontainer aware IDE or CLI, e.g. Visual Studio code
• or a Hugo Devbox-definition - 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 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 (e.g. code .)
2. start the devcontainer (in VSC it's F1 + Reopen in Devcontainer)
3. 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, 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 .
2. find out the IP address of the devconatiner by using docker ps and docker inspect <id of container>
3. when the container is up & running just open your browser with http://<DOCKER IP>:1313/

Possibility 2: Hugo in a devbox

Devboxes are locally isolated environments, managed by the Nix package manager. So first prepare the devbox.

Then

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

Editing

Documentation language

The documentation is done in Docsy-Theme.

So for editing content just goto the content-folder and edit content arrording to the Docsy documentation

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

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

After some installation time you have:

Final result in a web browser