79 votes

Comment puis-je synchroniser la documentation avec les pages Github ?

J'ai un projet avec plusieurs personnes et nous avons un README.md avec un tas de Markdown à la sauce GitHub qui est rendu sur notre page GitHub. Nous avons également mis en place une branche GitHub Pages qui est hébergée sous le sous-domaine de notre organisation GitHub, et nous avons utilisé l'attribut Générateur automatique de pages en chargeant simplement notre README.md lorsque nous avons créé notre page. Cependant, je remarque que lorsque je mets à jour notre README.md il ne met pas à jour la page du projet. Au lieu de cela, nous devons aller dans l'onglet des paramètres GitHub et recréer la page du projet, en rechargeant le fichier README.md quand on le fait.

Aussi, après avoir lu sur liaison relative travailler entre les fichiers de documentation sur les pages du répertoire du projet GitHub. J'aime beaucoup le format markdown car il permet de gagner beaucoup de temps en évitant d'avoir à écrire tout le HTML à la main pour notre documentation. Ce que j'aimerais cependant, c'est pouvoir disposer d'un seul fichier README.md qui peut inclure des liens relatifs vers d'autres fichiers de documentation situés à l'adresse suivante docs/*.md . J'espérais qu'il y avait une solution facile pour que mes autres fichiers de documentation puissent également être inclus dans ma branche gh-pages et être hébergés sous mon sous-domaine GitHub Pages et être rendus et/ou thématisés.

En d'autres termes, mes questions sont :

  • Existe-t-il un moyen de mettre automatiquement à jour mon fichier README.md sur le sous-domaine de ma page Github ?
    • [ EDIT ] : Non semble être la réponse si vous utilisez le générateur automatique de pages. Vous devez vous rendre sur la page des paramètres du dépôt et la recharger chaque fois qu'une modification est apportée afin de la mettre à jour.
       
  • Existe-t-il un moyen de faire en sorte que les liens relatifs à ma documentation dans mon fichier README.md fonctionnent sur mes pages Github, peut-être en synchronisant d'une manière ou d'une autre mes pages Github avec les liens relatifs à ma documentation ? /docs/*.md à mes pages Github et les rendre et/ou les thématiser d'une manière ou d'une autre ?
    • [ EDIT ] : D'après ce que j'ai appris depuis que j'ai rédigé cette question, il semble que cela ne soit possible que sur les pages GitHub grâce à l'utilisation d'un fichier générateur de site statique comme la pierre précieuse du rubis Jekyll et probablement quelques utilisations de la webhooks supportés par GitHub qui sont mentionnés dans les commentaires ci-dessous. J'essaie actuellement de trouver une solution optimale.
       
  • Mieux encore, y a-t-il un moyen encore plus simple de faire cela et peut-être d'avoir une seule copie de mon README.md et de ma documentation qui est utilisée à la fois sur les pages gh et sur ma branche principale et qui rend tout plus facile ?
    • [ EDIT ] : Il semble que celui-ci soit presque définitivement un non. Je pensais à la possibilité d'intégrer quelque chose dans GitHub pour permettre cela. Il semble qu'un meilleur support pour ce genre de choses pourrait être intégré dans les pages GitHub à l'avenir, ou du moins je l'espère vraiment.
       
  • Donnez-moi une autre meilleure solution que vous avez.

Merci beaucoup à l'avance.

[ EDIT ] : Cette question commence maintenant à recevoir une certaine attention et je continue également à faire des recherches à ce sujet. Je suis toujours ouvert et à la recherche de la solution la plus facile/optimale, probablement en utilisant des webhooks et Jekyll ou quelque chose de similaire. Je veux donner à plus de personnes la chance de répondre avant d'accepter la meilleure. Je sais qu'il doit y avoir des tonnes d'astuces individuelles que les gens utilisent pour cela et je suis sûr que quelqu'un a une excellente solution pour faire cela facilement.

37voto

Cory Gross Points 3118

Je vais poster une solution que j'ai mise en place qui tire parti du fait que GitHub Pages utilise Jekyll en utilisant déjà le générateur automatique de pages.

  1. git checkout gh-pages
  2. mkdir _layouts
  3. mv index.html _layouts
  4. git checkout master -- README.md
  5. mv README.md index.md
  6. Ajoutez le texte suivant à index.md


    layout: index

Vous devez également ouvrir le index.html et apportez les modifications suivantes :

  1. Supprimez le HTML rendu de la version markdown de votre fichier README.md fichier. Cela se situe généralement entre <section> o tags. Replace this HTML with the text {{ content }}` cela nous permettra d'utiliser ce fichier comme un jekyll. Le fichier auquel nous appliquons la mise en page sera placé là où se trouve la balise content.

  2. Localisez le CSS pour le thème de votre page de projet. Pour moi, c'était une ligne comme la suivante :

    <link rel='stylesheet' href='stylesheets/stylesheet.css' />

    Il convient de le modifier comme suit

    <link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />

  3. Toutes les autres ressources stockées sur votre site qui seront utilisées dans cette mise en page devront également être précédées du préfixe {{ site.path }} .

En faisant cela, Jekyll rendra le fichier markdown comme le contenu de l'objet index.html dans le _layouts répertoire. Afin d'automatiser ce processus non seulement pour le fichier README.md, mais aussi pour les autres documents que vous pouvez avoir dans votre branche principale, j'ai pris les mesures suivantes :

Créé le fichier appelé post-commit contenant les éléments suivants :

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # Layout prefix is prepended to each markdown file synced
    ###################################################################
    LAYOUT_PREFIX='---\r\nlayout: index\r\n---\r\n\r\n'

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    echo -e $LAYOUT_PREFIX > index.md
    cat README.md >> index.md
    rm README.md
    git add index.md
    git commit -a -m "Sync README.md in master branch to index.md in gh-pages"

    # Sync the markdown files in the docs/* directory
    ###################################################################
    git checkout master -- docs
    FILES=docs/*
    for file in $FILES
    do
        echo -e $LAYOUT_PREFIX | cat - "$file" > temp && mv temp "$file"
    done

    git add docs
    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following push if you want to auto push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git push origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

EDITAR: J'ai mis à jour le script ci-dessus à la fois pour les README.md et le markdown dans docs/* pour que les deux utilisent le même fichier de mise en page. C'est une bien meilleure configuration que celle que j'avais auparavant. Cette script va dans votre .git/hooks/ bash doit se trouver dans votre chemin.

Créer le fichier _config.yml avec les éléments suivants

markdown: redcarpet
path: http://username.github.io/reponame

Le script ci-dessus synchronise également les fichiers markdown trouvés dans le répertoire docs/* du répertoire master afin qu'ils puissent également être consultés sur le site GitHub Pages. La création de liens relatifs vers ces documents fonctionne si vous incluez la fonction jQuery suivante afin de supprimer l'attribut .md l'extension des ancrages sur le gh-pages branche. Vous pouvez ajouter le script suivant à index.html dans le _layouts répertoire :

$(document).on('ready', function () {
    $('a').each(function (i, e) {
        var href = e.href;
        if (href.search('.md') > 0)
            $(this).attr('href', href.split('.md')[0]);
    });
});

EDITAR: J'ai modifié le code ci-dessus dans mon dépôt, c'était une façon rapide et sale de le faire, mais cela ne fonctionnera pas correctement dans tous les cas si vous voyez ce que je veux dire . Par exemple, le fichier markdown company.mdata.md ne serait pas traité correctement. Pour corriger cela, je l'ai mis à jour avec le script suivant qui vérifie plus soigneusement le href et supprime l'extension si elle est trouvée. J'ai également rendu le script plus générique, lui permettant d'être utilisé pour supprimer d'autres extensions en changeant la balise ext variable. Voici le code :

$(function () {
    $('a').each(function () {
        var ext = '.md';
        var href = $(this).attr('href');
        var position = href.length - ext.length;
        if (href.substring(position) === ext)
            $(this).attr('href', href.substring(0, position));
    });
});

J'ai créé un dépôt d'exemple à CoryG89/docsync qui a un page du projet ici si vous voulez voir comment tout cela fonctionne.

5voto

kgryte Points 21

Ma solution au problème de la synchronisation d'un README avec une page Github s'écarte légèrement de ce qui précède. Au lieu d'utiliser un moteur JavaScript Markdown distinct, on peut utiliser l'API de Github pour renvoyer un fichier Markdown rendu en HTML.

  1. Récupérer le README.md de https://api.github.com/repos/<owner>/<repo>/contents/README.md .

  2. Décode la réponse en Base64 : window.atob( JSON.parse( blob ).content );

  3. Affichez le décodage README a https://api.github.com/markdown dans un corps JSON

     {
       "text": "<README>",
       "mode": "markdown",
       "context": "<owner>/<repo>"
     }
  4. Insérer le HTML rendu dans un élément DOM, comme cela est fait par Brad Rhodes .

Deux réserves à cette approche :

  1. Effectuer deux requêtes en série ralentit le chargement des pages.
  2. Peut rencontrer des limites de débit lors de l'accès à l'API Github.

Pour une page à faible trafic où le temps de chargement n'est pas critique (~1-2sec), la méthode ci-dessus fonctionne assez bien.

Pour voir un exemple, voir ce qui suit Page Github .

3voto

Nathan Points 732

J'ai quelques idées pour partager un seul fichier readme entre votre site de documentation et votre repo github principal :

  1. Vous pourriez utiliser une seule branche gh-pages qui contient à la fois votre code et un site de documentation jekyll. Votre dépôt pourrait être un peu encombré et vous devrez mettre un en-tête YAML en haut du readme. Il s'agit de presque supporte les liens relatifs. Le problème est que si vous voulez que Jekyll rende votre markdown, il lui donnera une extension .html. Il existe peut-être un moyen de configurer cela. Voici un exemple que j'ai mis au point pour voir si cela fonctionne.

  2. Vous pourriez utiliser des appels AJAX dans votre site de documentation pour lire le fichier readme à partir de votre branche principale, puis le rendre avec une balise Moteur de rendu Javascript Markdown . Cela prendra un peu plus de temps à charger et ne supportera pas les liens relatifs sans que vous n'écriviez un Javascript astucieux. C'est également plus difficile à mettre en œuvre que l'idée 1.

3voto

Matt Kantor Points 701

Une autre voie à envisager est la mise en place d'un crochet de pré-commission qui construit les pages pertinentes. Je fais cela dans un de mes dépôts . Il faudrait probablement abandonner le générateur automatique de pages et se contenter de pousser vers la page gh-pages Mais vous pouvez aussi faire quelque chose de fantaisiste pour transformer vos documents en HTML ou en un site Jekyll en tant que Nathan propose .

Dans ce dépôt Je pousse comme ça pour garder gh-pages identique identique à identique avec master . Il y a beaucoup de autres moyens pour faire ça aussi. Mais ce n'est peut-être pas l'idéal dans votre cas (vous ne voulez peut-être pas qu'ils soient identiques).

Quoi qu'il en soit, la raison pour laquelle j'avais proposé une prime sur cette question était que j'espérais que quelqu'un avait une meilleure méthode de travail. Cette méthode est un peu alambiquée et inflexible et elle exige que tout le monde garde ses crochets synchronisés.

1voto

Dave Syer Points 9749

Je veux aussi éditer les documents dans master et les publier dans gh-pages - j'aime garder les documents à jour avec le code source et cela semble être la meilleure façon. Il s'agit d'un travail en cours pour moi, mais j'ai pris Le script de Cory comme point de départ et nous l'avons un peu étendu pour qu'il fonctionne dès le départ, à condition qu'il y ait une branche gh-pages avec le code suivant _layouts (i.e. un site jekyll). Il convertit les clôtures de style backtick (pour les blocs de code) qui fonctionnent bien dans la navigation des sources de github, mais pas dans les pages gh. J'utilise un index.md avec un include pour le projet README.md pour que je puisse ajouter un en-tête et d'autres décorations. Cette version gère également la documentation dans tous les répertoires imbriqués appelés "docs", ce que je trouve utile dans un projet avec de multiples modules (pas des submodules git, juste des sous-répertoires) :

.git/hooks/post-commit

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # function to convert a plain .md file to one that renders nicely in gh-pages
    function convert {
        # sed - convert links with *.md to *.html (assumed relative links in local pages)
        # awk - convert backtick fencing to highlights (script from bottom of file)
        sed -e 's/(\(.*\)\.md)/(\1.html)/g' "$1" | awk -f <(sed -e '0,/^#!.*awk/d' $0) > _temp && mv _temp "$1"
    } 

    if ! git show-ref --verify --quiet refs/heads/gh-pages; then
        echo "No gh-pages, so not syncing"
        exit 0
    fi

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    mkdir -p _includes

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    if [ -f README.md ]; then
        cp README.md _includes/
        convert _includes/README.md
        git add README.md
        git add _includes/README.md
    fi

    # Generate index if there isn't one already
    ###################################################################
    if [ ! -f index.md ]; then
        echo -e '---\ntitle: Docs\nlayout: default\n---\n\n{% include README.md %}' > index.md
        git add index.md
    fi

    # Generate a header if there isn't one already
    ###################################################################
    if [ ! -f _includes/header.txt ]; then
        echo -e '---\ntitle: Docs\nlayout: default\nhome: \n---\n\n' > _includes/header.txt
        git add _includes/header.txt
    fi

    # Sync the markdown files in all docs/* directories
    ###################################################################
    for file in `git ls-tree -r --name-only master | grep 'docs/.*\.md'`
    do
        git checkout master -- "$file"
        dir=`echo ${file%/*} | sed -e "s,[^/]*,..,g"`
        cat _includes/header.txt | sed -e "s,^home: .*$,home: ${dir}/," > _temp
        cat "$file" >> _temp && mv _temp "$file"
        convert "$file"
        git add "$file"
    done

    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following push if you want to auto push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git push origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

exit $?

#!/usr/bin/awk
{
   # Replace backtick fencing (renders well when browsing github) with jekyll directives
   if (/```/) {
      IN = IN?0:1 # Are we already in a fenced section? Toggle.
      if (IN) { # If we are starting a fenced section
         if (/```\s*$/) {
           $0 = $0"text" # empty language is OK for backticks but not for jekyll
         }
         gsub(/```/, "{% highlight ")
         print $0" %}"
      } else { # ending a fenced section
        print "{% endhighlight %}" 
      }
    } else { # not a fencing line
      if (IN) { # but in a fenced section, so add indent to make sure code is rendered with <pre>
        print "    "$0
      } else {
        print
      }
    }
}

Une autre variation par rapport à l'original est qu'il fixe une variable page.home dans toutes les pages. Cela peut être utilisé pour localiser le chemin relatif du répertoire racine, et donc pour localiser des ressources statiques comme les css. Dans _layouts/.default.html Je l'ai fait :

<link rel="stylesheet" href="{{ page.home }}css/main.css">

De cette façon, je peux modifier les css, construire le site Jekyll localement et voir le résultat dans un navigateur sans avoir à attendre que Github le construise sur le serveur.

Prograide.com

Prograide est une communauté de développeurs qui cherche à élargir la connaissance de la programmation au-delà de l'anglais.
Pour cela nous avons les plus grands doutes résolus en français et vous pouvez aussi poser vos propres questions ou résoudre celles des autres.

Powered by:

X