search

2p2r / velobs_web

Application web permettant aux cyclistes de signaler les problèmes sur les aménagements cyclables.
GNU General Public License v3.0
22 stars 14 forks source link

Passage de la doc de odt à markdown #212

Closed lutangar closed 5 years ago

lutangar commented 5 years ago

Voici une proposition pour passer la documentation du format odt au format markdown.

Motivation Le fichier Markdown peut être lu/écrit tel quel, sans besoins d'un logiciel supplémentaire. Il sert de forme normale; il peut être exporté vers une multitude de format cible (html, etc...)

voir aussi les nombreux générateurs de documentations tel que gitbook

Approche L'approche pour passer du document initial à un format markdown a été la suivante:

  1. Passage de odt à markdown brut: 
    pandoc INSTALL.odt -o INSTALL.md
  2. Rechercher/Remplacer les caractères initialement échappés, par exemple : \_ -> _
  3. Repasse manuelle sur les niveaux de titres
  4. Manuellement passer en emphase (code) les variables et autres morceaux de codes
  5. Extraire les images du document odt (un document odt est une archive dans laquelle on peut trouver un dossier media/ si extraite) et les insérer aux bons endroits manuellement
gerald2545 commented 5 years ago

merci pour ce transfert vers markdown qui va faciliter la maintenance. Y'a-t-il possibilité de mettre un "sommaire" avec lien vers les différentes parties de la doc? La numérotation des différentes parties de l'interface (avant image3) n'est pas correcte : transformer la numérotation romaine en numérotation arabe

merci d'avance

lutangar commented 5 years ago

@gerald2545 la numérotation a été corrigé, et un le lien a été changé sur le README.

En ce qui concerne le sommaire, c'est tout à fait possible, grâce aux ancres notamment, mais la maintenance d'un sommaire peut devenir laborieuse à chaque mise à jours.

Dans un second temps, il peut être intéressant de réfléchir à une meilleur organisation de la documentation de manière générale, par exemple:

...ou bien encore exploiter la fonction "wiki" de Github https://guides.github.com/features/wikis/

lutangar commented 5 years ago

Bonjour @gerald2545,

La conversion de la documentation utilisateur a également été ajoutée à cette PR.

Si cette conversion est satisfaisante sur le fond et la forme, je propose d'intégrer ces changements.

Puis je pourrais éventuellement proposer une meilleur organisation et mise en avant de cette documentation dans une prochaine PR. (export, wiki ou autre)

gerald2545 commented 5 years ago

OK, merci pour ton travail. A prendre en compte avant de faire le merge :

lutangar commented 5 years ago

valider le bon formatage du markdown (attention aux captures d'écran qui sont incluses dans les puces)

Pour un avoir un aperçu rapide du rendu, tu peux directement consulter ma branche : https://github.com/lutangar/velobs_web/tree/doc_markdown Si tu souhaites une convention particulières pour les images des puces, n'hésites pas à en faire part.

vérifier les endroits où cette documentation est référencée pour y changer les liens

Les liens ont été corrigés et en plus ils pointent maintenant directement sur les bonnes ancres!

gerald2545 commented 5 years ago

c'est en effet après consultation du résultat sur ta branche que je me suis permis de faire mes remarques. Certaines images sont bien intégrées d'autres non (e.g. 100000000000005A0000008B8667BE44A7E99238.png : Accéder à une observation > Via la carte). J'en ai repéré 2 ou 3 comme ça.

Concernant les liens vers cette documentation, je pensais plus aux sites externes qui pointent vers elle...mais si en plus tu as corrigé les liens internes, c'est cool. Je vois que tu es toujours en cours de modif. Dis moi quand tu penses avoir finalisé merci pour ton travail

Le mer. 17 avr. 2019 à 15:41, Johan Dufour notifications@github.com a écrit :

valider le bon formatage du markdown (attention aux captures d'écran qui sont incluses dans les puces)

Pour un avoir un aperçu rapide du rendu, tu peux directement consulter ma branche : https://github.com/lutangar/velobs_web/tree/doc_markdown Si tu souhaites une convention particulières pour les images des puces, n'hésites pas à en faire part.

vérifier les endroits où cette documentation est référencée pour y changer les liens

Les liens ont été corrigés et en plus ils pointent maintenant directement sur les bonnes ancres!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/2p2r/velobs_web/pull/212#issuecomment-484094578, or mute the thread https://github.com/notifications/unsubscribe-auth/AJtNJnKFHs3claSoAaoN1xSfmfaU8RCNks5vhyR2gaJpZM4csJru .

-- VelObs : remontez vos problèmes lors des déplacements à vélo sur le web https://velobs.2p2r.org/ ou sur android https://play.google.com/store/apps/details?id=org.deuxpiedsdeuxroues.velobs.tlse&hl=fr (une appli 2P2R https://2p2r.org/) Pedibus labégeois https://emilepattesblog.wordpress.com/ Soutenez ICEA http://icea-enr.fr/, Inititiative Citoyenne pour une Energie Alternative, prenez ou offrez des parts sociales pour devenir co-propriétaire de panneaux photovoltaïques Consommez de l'énergie éléctrique verte renouvelable avec ENERCOOP http://www.enercoop.fr/

lutangar commented 5 years ago

Après de multiples essais je pense avoir trouvé la bonne méthode de calage pour les images.

Concernant les liens vers cette documentation, je pensais plus aux sites externes qui pointent vers elle...

Difficile de te proposer quelque-chose à ce niveau là.

Dis moi quand tu penses avoir finalisé

Ok pour moi.

merci pour ton travail

Non de rien, merci pour le tiens :+1:

lutangar commented 5 years ago

Désolé pour ces derniers push, j'essayais en vain de commit le fichier lib/js/key.js.template avec des saut de lignes windows pour éviter le diff inutile... mais sans succès :/