README.md 3.71 KB
Newer Older
 JosephK's avatar
JosephK committed
1
2
[![](https://framagit.org/assets/favicon-075eba76312e8421991a0c1f89a89ee81678bcde72319dd3e8047e2a47cd3a42.ico)](https://framagit.org)

 JosephK's avatar
JosephK committed
3
🇬🇧 **Framasoft uses GitLab** for the development of its free softwares. Our Github repositories are only mirrors.
 JosephK's avatar
JosephK committed
4
5
If you want to work with us, **fork us on [framagit.org](https://framagit.org)**. (no registration needed, you can sign in with your Github account)

 JosephK's avatar
JosephK committed
6
🇫🇷 **Framasoft utilise GitLab** pour le développement de ses logiciels libres. Nos dépôts Github ne sont que des miroirs.
 JosephK's avatar
JosephK committed
7
8
9
Si vous souhaitez travailler avec nous, **forkez-nous sur [framagit.org](https://framagit.org)**. (l'inscription n'est pas nécessaire, vous pouvez vous connecter avec votre compte Github)
* * *

 JosephK's avatar
JosephK committed
10
Site de documentation et d'accueil (basée sur Honkit) des contributeurs aux projets de Framasoft.
 JosephK's avatar
JosephK committed
11
12
13
14
15
16
17
18
19
[participer.framasoft.org](https://participer.framasoft.org)

* * *

## Contribuer à la documentation

### Rédaction

Les fichiers sont rédigés avec [la syntaxe markdown](https://docs.framasoft.org/fr/mattermost/help/messaging/formatting-text.html)
 JosephK's avatar
JosephK committed
20
mais Honkit accepte aussi la syntaxe HTML.
 JosephK's avatar
JosephK committed
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

Par contre, il n'est pas possible de mixer les 2 syntaxes dans un même bloc.

Si vous voulez ajouter des liens internes, il faut faire attention à pointer vers
les pages `.html` correspondantes au `.md` du dossier.

### Méthode de travail

https://framagit.org/spf/Tutos/blob/master/Git/translate.md
(voir si le tuto est adapaté pour la documentation)

  1. Forker
  2. Créer une branche
  3. Faire les changements (commit)
  4. Demander à intégrer les changements (merge request)
  5. Discuter / rectifier

### Structure

Les documentations anglaise et française sont totalement indépendantes.

La documentation de chaque Framaprojet doit être enregistrée dans un dossier.

Dans ce dossier, créer un dossier `images` contenant les captures d'écran
et un fichier `README.md` qui contiendra la page d'accueil de présentation du projet

Pour ajouter ensuite le Framaprojet dans la colonne de gauche et sur la page d'accueil,
il faut éditer les fichiers `SUMMARY.md` et `README.md` (à la racine dans le dossier `fr`).

Dans `SUMMARY.md`, il n'est pas possible d'afficher une arborescence
de plus de 2 niveaux et les titres ne sont pas pris en compte
(ils ne sont laissés qu'à titre indicatif).

 JosephK's avatar
JosephK committed
54
Chaque lien `.md` trouvé dans ce fichier sera pris en compte par Honkit
 JosephK's avatar
JosephK committed
55
56
57
58
59
60
pour créer le fichier `.html` correspondant.
Les fichiers qui ne s'y trouvent pas seront placé dans le dossier
comme de simples fichiers statiques (au même titre que les images)

## Créer une copie locale de la documentation

 JosephK's avatar
JosephK committed
61
Pour avoir un aperçu du rendu du site il peut être souhaitable d'installer Honkit localement.
 JosephK's avatar
JosephK committed
62

 JosephK's avatar
JosephK committed
63
### Installation de NodeJS
 JosephK's avatar
JosephK committed
64

 JosephK's avatar
JosephK committed
65
Installez NodeJS et NPM :
 JosephK's avatar
JosephK committed
66
67
68
69
70
71
72
73
74

    sudo apt-get install nodejs-legacy npm

### Générer la documentation

Clonez votre fork de la documentation

    git clone https://framagit.org/<utilisateur>/framasoft/participer.git

 JosephK's avatar
JosephK committed
75
Depuis le dossier `participer` procédez à l'installation de honkit et des plugins requis
 JosephK's avatar
JosephK committed
76
77
78
(la liste des plugins et leur configuration se trouve dans le fichiers `book.json`)

    cd participer
 JosephK's avatar
JosephK committed
79
80
81
    npm i
    npx honkit init
    npx honkit serve
 JosephK's avatar
JosephK committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95

Si tout s'est bien déroulé (la commande se termine par `Serving book on…`,
la copie du site peut être consultée sur :

    http://localhost:4000/

Plus il y a de pages, plus le temps de chargement est long.

Il vaut mieux prendre le temps de finir les changements et redémarrer
le serveur manuellement quant on a fini.

Si vous disposez d'un serveur web en local, plutôt que de se servir du serveur
nodejs, vous pouvez aussi créer le site manuellement avec la commande

 JosephK's avatar
JosephK committed
96
    npx honkit build
 JosephK's avatar
JosephK committed
97
98

et copier le dossier `_book` où vous le voulez sur le serveur web.