Stephan Lo
9e509ed265
- 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).
153 lines
4.5 KiB
Markdown
153 lines
4.5 KiB
Markdown
# IPCEI-CIS Developer Framework Documentation
|
|
|
|
[](https://gohugo.io/)
|
|
[](https://www.docsy.dev/)
|
|
[](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
|
|
|
|
## Quick Start
|
|
|
|
### For Documentors (Content Writers)
|
|
|
|
If you want to contribute to the documentation, see **[README-documentor.md](./README-documentor.md)** for detailed instructions.
|
|
|
|
**Quick start:**
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd ipceicis-developerframework
|
|
|
|
# Install dependencies
|
|
task deps:install
|
|
|
|
# If using Devbox
|
|
devbox shell
|
|
|
|
# Start development server
|
|
task serve
|
|
|
|
# Open browser at http://localhost:1313
|
|
```
|
|
|
|
### For Readers
|
|
|
|
The documentation is published at:
|
|
- **Production**: `https://<production-url>`
|
|
- **Development**: `https://<dev-url>`
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── 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
|
|
```
|
|
|
|
## Technology Stack
|
|
|
|
- **[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-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
|
|
|
|
## 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-documentor.md](./README-documentor.md).
|