Salta el contingut

Exemple pràctic de Docs as Code

Context del projecte

Aplicació web REST amb:

  • Backend en PHP (Laravel)
  • Base de dades MySQL
  • Desplegament amb Docker
  • Repositori Git

La documentació:

  • Es guarda dins del repositori
  • Està escrita en Markdown
  • Es versiona amb Git
  • Es publica automàticament amb GitHub Pages

1. Estructura del repositori

projecte-daw/
│
├── app/
├── database/
├── docker/
├── routes/
├── tests/
│
├── docs/
│   ├── index.md
│   ├── arquitectura.md
│   ├── instal·lacio.md
│   ├── api.md
│   ├── base_dades.md
│   └── desplegament.md
│
├── mkdocs.yml
├── README.md
└── docker-compose.yml

Observa que la carpeta docs/ forma part del mateix repositori que el codi.

2. Exemple real de documentació (Markdown)

📄 docs/arquitectura.md

# Arquitectura del sistema

## Patró utilitzat
Arquitectura MVC.

## Components principals

- Backend Laravel
- Base de dades MySQL
- Servidor Nginx
- Contenidors Docker

## Diagrama simplificat

Client → Nginx → Laravel → MySQL

📄 docs/instal·lacio.md

# Instal·lació del projecte

## Requisits previs
- Docker
- Docker Compose
- Git

## Clonar repositori

git clone https://github.com/usuari/projecte-daw.git

## Iniciar contenidors

docker-compose up -d

## Accedir a l'aplicació

http://localhost:8080

3. Fitxer de configuració MkDocs

📄 mkdocs.yml

site_name: Projecte DAW
nav:
  - Inici: index.md
  - Arquitectura: arquitectura.md
  - Instal·lació: instal·lacio.md
  - API: api.md
  - Base de dades: base_dades.md
  - Desplegament: desplegament.md
theme:
  name: material

Aquest fitxer permet generar una web navegable de documentació.

4. Publicació automàtica (Integració contínua)

Exemple GitHub Actions

📄 .github/workflows/docs.yml

name: Deploy Docs

on:
  push:
    branches:
      - main

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Install MkDocs
        run: pip install mkdocs mkdocs-material
      - name: Deploy
        run: mkdocs gh-deploy --force

Cada vegada que es fa un push a main, la documentació es publica automàticament.

Això és Docs as Code + CI/CD.

5. Flux de treball real en equip

  1. Desenvolupador crea una nova funcionalitat.
  2. Actualitza docs/api.md.
  3. Ho afig al repositori local.

  4. Fa commit:

    git commit -m "Afegit endpoint de registre d'usuari"

  5. Fa push per actualitzar el repositori remot.

  6. La documentació es regenera automàticament.
  7. L’equip pot consultar-la actualitzada en línia.