https://github.com/apikcloud/docs
The Apik Way
https://github.com/apikcloud/docs
documentation
Last synced: 5 months ago
JSON representation
The Apik Way
- Host: GitHub
- URL: https://github.com/apikcloud/docs
- Owner: apikcloud
- License: other
- Created: 2025-04-15T12:18:01.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-18T11:15:04.000Z (6 months ago)
- Last Synced: 2025-12-21T01:43:00.506Z (6 months ago)
- Topics: documentation
- Language: Shell
- Homepage: https://apikcloud.github.io/docs/
- Size: 481 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
---
## Overview
This repository hosts **Apik’s internal engineering documentation** — our shared technical foundation for all teams.
It defines our **development standards**, **workflows**, **tooling**, and **infrastructure guidelines**, ensuring coherence and quality across projects.
The full documentation lives in the `/docs` directory and is automatically deployed to GitHub Pages at:
👉 [https://apikcloud.github.io/docs/](https://apikcloud.github.io/docs/)
---
## Philosophy
Every developer should be able to understand, extend, or debug any Apik project without friction.
This documentation captures our collective know-how and evolves continuously through collaboration.
---
## Working Language
All documentation, code comments, and commit messages are written in **English**.
French versions are generated automatically for internal readability when needed.
---
## Structure
- `/docs` — Core documentation (development, workflow, CI/CD, quality, infrastructure, etc.)
- `/docs/_media` — Shared assets (logos, diagrams, images)
- `/docs/_sidebar.md` — Documentation sidebar structure
- `/docs/index.html` — [Docsify](https://docsify.js.org/) configuration for live rendering
- `/docs/DOCUMENTATION.md` — Aggregated documentation (auto-generated, do not edit manually)
- `/scripts` — Automation scripts for translation and aggregation
- `.github/workflows` — CI pipelines for translation, validation, and aggregation
The old `_module/` folder has been merged into a single file: `10-module.md`.
---
## Automation
Two main GitHub Actions maintain the documentation:
| Workflow | Description |
|-----------|--------------|
| **Translate** | Generates a French version from the English source. (deactivated) |
| **Aggregate** | Builds a single Markdown file for offline use. (deactivated) |
| **pages-build-deployment** | Deploys the documentation to GitHub Pages. |
---
## Contributing
This documentation is a **living reference**.
All contributions must go through **Pull Request** review by the **Quality Team** and, when applicable, the **Technical Referent**.
**Guidelines:**
- Keep edits **concise**, **consistent**, and **in English**.
- Reference related tickets or discussions in commit messages.
- Keep branches short-lived: merge early, merge often.
- Each branch should focus on a single, clear topic.
- Avoid long-running branches or parallel document versions.
- Documentation changes are collaborative but should remain traceable and easy to review.
### Branch Naming Convention
The documentation repository follows a **trunk-based development workflow** similar to our Odoo projects, with lightweight and short-lived branches.
#### Main branch
- **`main`** is the source of truth and represents the published version of the documentation (public or internal).
#### Working branches
Branches are created for short, focused contributions and merged quickly into `main` using **squash merges**.
Use clear and thematic prefixes instead of ticket-based names:
| Prefix | Purpose | Example |
|---------|----------|----------|
| `doc/` | New documentation page or section | `doc/hooks`, `doc/migrations` |
| `fix/` | Minor fix or correction | `fix/typo`, `fix/links` |
| `rev/` | Major revision or restructuring | `rev/architecture`, `rev/sections-order` |
| `draft/` | Work in progress, not yet validated | `draft/quality-charter` |
_This convention keeps the documentation process consistent with our trunk-based philosophy while staying lightweight and contributor-friendly._
### Running Locally
```bash
make setup
make serve
```
```bash
# To aggregate and translate documentation manually
make translate
make aggregate
```
---
## Drafts and Proposals
Any unvalidated or in-progress document must begin with this badge:
```markdown
Status: Draft — Pending Review and Approval
```
This clearly indicates that the page is **provisional** and subject to review.
---
## License
This repository is distributed under the [CC BY-NC-ND 4.0 License](./LICENSE).