88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
# 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
|
|
|
|
|
|
|
|
#### Hugo server is running and (typically) listens to localhost:1313
|
|
|
|
After some installation time you have:
|
|
|
|
|
|
|
|
### Final result in a web browser
|
|
|
|
|