Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity

chore(hugo): Added devbox for hugo processing. Improved README documentation.

Browse source
This commit is contained in:
Stephan Lo 2024-11-05 09:38:29 +01:00
parent 08847aac0a
commit a845e0fcde
3 changed files with 177 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

73
README.md
View file

@ -6,58 +6,83 @@ This repo contains business and architectural design and documentation of the De
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.
Hugo is a static site renderer - so to get the documentation site presented you need a running Hugo processor. Therefore there is
### Installation
* 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
To get a locally running documentation editing and presentation environment, follow these steps:
## 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://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/`
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`
If you want to run the devcontainer without VS Code, you can use npn to run it inside a docker container:
### Possibility 1: Hugo in a devcontainer
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/`
[`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.
### Editing
There are several options to create and run the devcontainer - we present here two:
#### Documentation language
#### 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
## Commiting
After having finished a unit of work commit and push.
## Annex
# Annex
### Installation steps illustrated
## Installation steps illustrated
When you run the above installation, the outputs could typically look like this:
#### Steps 4/5 in Visual Studio Code
### In Visual Studio Code
##### Reopen in Container
#### Reopen in Container
![vsc-f1](./assets/images/vsc-f1.png)
##### Hugo server is running and (typically) listens to localhost:1313
#### 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
### Final result in a web browser
![browser](./assets/images/browser.png)