DevFW-CICD/website-and-documentation
23
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(docs): restructure documentation with new framework and templates

Browse source 
- Archive old docs to docs-old/ for reference
- Create new top-down documentation structure:
  * Platform Overview: purpose, audience, product structure
  * Components: individual platform components (Forgejo, Kubernetes, Backstage)
  * Getting Started: onboarding and quick start guides
  * Operations: deployment, monitoring, troubleshooting
  * Governance: ADRs, project history, compliance
- Add DOCUMENTATION-GUIDE.md with writing guidelines and templates
- Add component template (TEMPLATE.md) for consistent documentation
- Simplify root README and move technical docs to doc/ folder
- Update test configuration:
  * Exclude legacy content from markdown linting
  * Relax HTML validation for theme-generated content
  * Skip link checking for legacy content in test:links
  * Keep 'task test' clean for technical writers (100% pass)
  * Add 'task test:full' with comprehensive link checking
- Update home page with corrected markdown syntax
- Fix internal links in archived content

BREAKING CHANGE: Documentation structure changed from flat to hierarchical top-down approach
This commit is contained in:
Stephan Lo 2025-11-16 13:32:10 +01:00
parent 2ec2efe9fc
commit 62999b41d0
196 changed files with 907 additions and 160 deletions
Download patch file Download diff file Expand all files Collapse all files

154
README.md
View file

@ -1,153 +1,33 @@
# IPCEI-CIS Developer Framework Documentation
# EDP - Edge Developer Platform
[![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/)
This repository contains the comprehensive documentation for the IPCEI-CIS Developer Framework, including:
- 🏗️ **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
Documentation for the edgeDeveloperFramework (eDF) project and the resulting Edge Developer Platform (EDP) product suite.
## Quick Start
### For Technical Writers (Content Writers)
If you want to contribute to the documentation, see **[README-technicalWriter.md](./README-technicalWriter.md)** for detailed instructions.
**Quick start:**
```bash
# Clone the repository
git clone <repository-url>
cd ipceicis-developerframework
# Install dependencies
task deps:install
task deps
# If using Devbox
devbox shell
# Start development server
# Start local development server
task serve
# Open browser at http://localhost:1313
# Run tests
task test
# Build production site
task build
```
### For Readers
## Documentation
The documentation is published at:
- **Production**: `https://<production-url>`
- **Development**: `https://<dev-url>`
* [Developer Guide](doc/README-developer.md)
* [Technical Writer Guide](doc/README-technical-writer.md)
* [Release Notes](doc/RELEASE.md)
## Project Structure
## Project
```
.
├── content/ # Documentation content (Markdown)
│ └── en/
│ ├── docs/ # Main documentation
│ │ ├── architecture/ # Architecture docs with LikeC4
│ │ ├── documentation/ # Technical Writer 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
```
This is a Hugo-based documentation site for the Edge Developer Platform, built as part of the IPCEI-CIS project.
## Technology Stack
**Website:** Access the documentation at the deployed URL or run locally with `task serve`
- **[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
## Available Tasks
View all tasks:
```bash
task --list
```
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
### Option 1: Devbox (Recommended)
[Devbox](https://www.jetify.com/devbox/) provides an isolated, reproducible environment:
```bash
# Install Devbox (if not already installed)
curl -fsSL https://get.jetify.com/devbox | bash
# Enter the shell
devbox shell
# All tools are now available in correct versions
hugo version
node --version
```
### Option 2: VS Code Dev Container
The `.devcontainer` folder contains the configuration for a containerized development environment:
1. Open in VS Code
2. Press `F1` → "Reopen in Container"
3. Wait for container to build
4. Development server starts automatically
### Option 3: Manual Installation
Install the following tools:
- Hugo Extended (v0.151.0+)
- Node.js (v24+)
- Go (for htmltest)
- Task (task runner)
## Contributing
We welcome contributions! Please:
1. Read [README-technicalWriter.md](./README-technicalWriter.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
## Documentation Guidelines
- **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
## License
[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-technicalWriter.md](./README-technicalWriter.md).
For detailed information, see the documentation in the `doc/` folder.