La documentazione è una cosa seria.

me medesimo


Spesso ci troviamo a creare documentazione per i nostri progetti in formato Markdown.


L’ideale è poter agilmente, generare un sito per la documentazione, a partire da questi file.

Couscous.io

Cercando in rete esistono molto soluzioni, oggi vi presento Couscous, che presenta una curva di apprendimento davvero sorprendente.


Cercherò di prendere un qualsiasi progetto su Github, dove vengono creati progetti sia direttamente dedicati alla documentazione che progetti dove si può trovare una cartella destinata alla raccolta di documenti.


Per creare un sito di documentazione dobbiamo avere 3 cose:

  • un tool da riga di comando per generare il sito statico
  • un template configurabile per il sito che andrà generato
  • dei file markdown da usare allo scopo


Couscous si presenta con dei template di esempio; in questo caso ho scelto Template-ReadTheDocs
Non è importante quale progetto possiate scegliere, io vado a prendermi le WordPress Coding Standards Docs per questo tutorial.


Per installare Couscous e avere il comando di cui parlavo sopra, andate nel Get Started per i dettagli


Ok Fatto? Direbbe Muciaccia


Ora non vi resta che seguire i seguenti comandi


Clonare il progetto da cui generare la documentazione

git clone https://github.com/WordPress/wpcs-docs


Clonare il progetto da usare come template

git clone https://github.com/CouscousPHP/Template-ReadTheDocs

copiare i file markdown all’interno della cartella del template scelto nel mio caso Template-ReadTheDocs.
Creo, in questo caso, per essere ordinato una cartella docs dentro la cartella Template-ReadTheDocs di nome docs

mkdir docs

Copio i file markdown dentro la stessa

cp  -r wpcs-docs/*  Template-ReadTheDocs/docs

Ci spostiamo nella cartella del template ed andiamo ad editare il file couscous.yml per poter sistemare il menu laterale; così facendo, indicheremo quali file vanno richiamati al click dei menu items.

cd Temmplate-ReadTheDocs

sotto al commento # The left menu bar del file couscous.yml troverete un menu di prova, cambiatelo così:

# The left menu bar
menu:
    items:
        best-practices:
            text: Best Practices
            relativeUrl: docs/index.html
        wordpress-coding-standards:
            text: WordPress Coding Standards
            relativeUrl: docs/wordpress-coding-standards.html
        Handbook:
            text: Coding Standards Handbook
            absoluteUrl: https://developer.wordpress.org/coding-standards/

ora sempre dalla cartella del template andiamo a lanciare il comando per auto-generare il sito statico per la nostra documentazione

couscous preview

aprendo il browser all’indirizzo locale http://127.0.0.1:8000, ci troveremo davanti ad un sito con menu laterale, dove, cliccando nelle relative voci del menu potete navigare tra i 2 documenti che avete agganciato alle singole voci di menu; l’ultima vi indirizzerà al sito dove è ospitato l’handbook ufficiale.


Ultimo passaggio è quello di poter indicare, invece che la pagina di default di Couscous, una scelta da voi.


Dobbiamo caricare nel file README.md che troviamo nella cartella del template il contenuto della index.md e aggiungere in ogni file markdown presenti nelle voci di menu, la notazione che riporta il menu item code, così da vederlo evidenziato nel menu

Più facile da fare che da dire, apriamo il file README.md e index.md e mettiamo l’intestazione

---
currentMenu: best-practices
---

apriamo il file della seconda voce di menu, wordpress-coding-standards.md e mettiamo

---
currentMenu: wordpress-coding-standards
---

e così via, fino ad ottenere il nostro menu

Conclusioni

Il motto di Couscous è

Couscous is built for simplicity

Credo sia un motto azzeccato.

Di static site generator ne abbiamo diversi la fuori, ma questa soluzione è davvero immediata, dulcis in fundo, ha anche un comando per il deploy verso le gh-pages . Se invece intendete metterlo altrove è facile scoprire che il sito viene generato sotto la cartella .couscous/generated a partire dalla radice dove avrete generato il sito.