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

docs: consolidate root documentation to README-* structure

Browse source 
- Created README-documentor.md: comprehensive guide for content contributors
- Created README-likec4.md: architecture modeling guide (merged from README-ARCHITECTURE.md + LIKEC4-QUICKSTART.md)
- Enhanced README-developer.md:
  - Added Docker/Container Build section (from DOCKER.md)
  - Expanded Testing section (from TESTING.md)
  - Added Version Management section (from VERSIONS.md)
  - Added LikeC4 tasks reference
- Updated README.md: modernized with badges and clear structure
- Deleted redundant files:
  - DOCUMENTOR-GUIDE.md (ASCII art, redundant to README-documentor.md)
  - DOCKER.md (integrated into README-developer.md)
  - TESTING.md (integrated into README-developer.md)
  - README-ARCHITECTURE.md (merged into README-likec4.md)
  - LIKEC4-QUICKSTART.md (merged into README-likec4.md)
  - VERSIONS.md (integrated into README-developer.md)
- Added devbox shell step to local-development.md

All hands-on documentation now follows README-* naming convention.
RELEASE.md retained as process documentation (not hands-on guide).
This commit is contained in:
Stephan Lo 2025-11-07 15:48:55 +01:00
parent 9921e07e3e
commit 9e509ed265
11 changed files with 1127 additions and 644 deletions
Download patch file Download diff file Expand all files Collapse all files

163
README.md
View file

@ -1,88 +1,153 @@
# IPCEICIS-DeveloperFramework Documentation
# IPCEI-CIS Developer Framework Documentation
This repo contains business and architectural design and documentation of the DeveloperFramework subproject of IPCEI-CIS.
[![Built with Hugo](https://img.shields.io/badge/Built%20with-Hugo-pink.svg)](https://gohugo.io/)
[![Styled with Docsy](https://img.shields.io/badge/Styled%20with-Docsy-blue.svg)](https://www.docsy.dev/)
[![Architecture with LikeC4](https://img.shields.io/badge/Architecture-LikeC4-purple.svg)](https://likec4.dev/)
## How to read and contribute to this documentation locally
This repository contains the comprehensive documentation for the IPCEI-CIS Developer Framework, including:
The documentation is done in [Hugo-format](https://gohugo.io).
- 🏗️ **Architecture Documentation** - Interactive C4 diagrams and system design
- 📖 **User Guides** - How to use and develop with the platform
- 📝 **ADRs** - Architecture Decision Records
- 🚀 **Platform Features** - Component documentation and guides
Hugo is a static site renderer - so to get the documentation site presented you need a running Hugo processor. Therefore there is
## Quick Start
* 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
### For Documentors (Content Writers)
## Local installation of the Hugo documentation system
If you want to contribute to the documentation, see **[README-documentor.md](./README-documentor.md)** for detailed instructions.
We describe two possible ways (one with devcontainer, one with devbox) to get the Hugo-documentation system locally running.
**Quick start:**
For both prepare the following three steps:
```bash
# Clone the repository
git clone <repository-url>
cd ipceicis-developerframework
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`
# Install dependencies
task deps:install
### Possibility 1: Hugo in a devcontainer
# If using Devbox
devbox shell
[`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.
# Start development server
task serve
There are several options to create and run the devcontainer - we present here two:
# Open browser at http://localhost:1313
```
#### Option 1: Run the container triggered by and connected to an IDE, e.g. VS Code
### For Readers
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/`
The documentation is published at:
- **Production**: `https://<production-url>`
- **Development**: `https://<dev-url>`
#### Option 2: Run the container natively
## Project Structure
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.
```
.
├── content/ # Documentation content (Markdown)
│ └── en/
│ ├── docs/ # Main documentation
│ │ ├── architecture/ # Architecture docs with LikeC4
│ │ ├── documentation/ # Documentor guides
│ │ └── v1/ # Legacy documentation
│ └── blog/ # Blog posts
├── resources/ # LikeC4 architecture models
│ ├── edp-likec4/ # Platform architecture
│ └── doc-likec4/ # Documentation platform architecture
├── layouts/ # Hugo templates & shortcodes
├── assets/ # SCSS, fonts, images
├── static/ # Static files (JS, CSS, images)
├── Taskfile.yml # Task automation
└── devbox.json # Devbox environment definition
```
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/`
## Technology Stack
### Possibility 2: Hugo in a devbox
- **[Hugo](https://gohugo.io/)** - Static site generator
- **[Docsy](https://www.docsy.dev/)** - Documentation theme
- **[LikeC4](https://likec4.dev/)** - Interactive architecture diagrams
- **[Task](https://taskfile.dev/)** - Task runner
- **[Devbox](https://www.jetify.com/devbox/)** - Development environment
[`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/).
## Available Tasks
Then
View all tasks:
```bash
task --list
```
1. ```devbox shell```
1. In the shell: ```hugo serve```
Common tasks:
- `task serve` - Start development server
- `task build` - Build production site
- `task test` - Run all tests
- `task likec4:generate` - Generate LikeC4 webcomponents
- `task likec4:validate` - Validate LikeC4 models
## Development Environments
## Editing
### Option 1: Devbox (Recommended)
### Documentation language
[Devbox](https://www.jetify.com/devbox/) provides an isolated, reproducible environment:
The documentation is done in [Docsy-Theme](https://www.docsy.dev/).
```bash
# Install Devbox (if not already installed)
curl -fsSL https://get.jetify.com/devbox | bash
So for editing content just goto the `content`-folder and edit content arrording to the [Docsy documentation](https://www.docsy.dev/docs/adding-content/)
# Enter the shell
devbox shell
## Commiting
# All tools are now available in correct versions
hugo version
node --version
```
After having finished a unit of work commit and push.
### Option 2: VS Code Dev Container
# Annex
The `.devcontainer` folder contains the configuration for a containerized development environment:
## Installation steps illustrated
1. Open in VS Code
2. Press `F1` → "Reopen in Container"
3. Wait for container to build
4. Development server starts automatically
When you run the above installation, the outputs could typically look like this:
### Option 3: Manual Installation
### In Visual Studio Code
Install the following tools:
- Hugo Extended (v0.151.0+)
- Node.js (v24+)
- Go (for htmltest)
- Task (task runner)
#### Reopen in Container
## Contributing
![vsc-f1](./assets/images/vsc-f1.png)
We welcome contributions! Please:
#### Hugo server is running and (typically) listens to localhost:1313
1. Read [README-documentor.md](./README-documentor.md) for documentation guidelines
2. Check existing [ADRs](./content/en/docs/decisions/) for architectural context
3. Create a branch for your changes
4. Run `task test` before committing
5. Submit a pull request
After some installation time you have:
## Documentation Guidelines
![vsc-hugo](./assets/images/vsc-hugo.png)
- **Write in present tense** - "The system processes..." not "will process"
- **Use architecture diagrams** - LikeC4 for interactive diagrams
- **Keep it concise** - Readers appreciate brevity
- **Test locally** - Run `task serve` and verify changes
- **Update regularly** - Stale docs are worse than no docs
### Final result in a web browser
## License
![browser](./assets/images/browser.png)
[License information here]
## Support
- **Issues**: [Issue Tracker](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/website-and-documentation/issues)
- **Discussions**: [Forum/Chat Link]
- **Documentation**: This repository
---
For detailed documentation contribution guidelines, see [README-documentor.md](./README-documentor.md).