web-dev-qa-db-fra.com

Afficher JavaDocs sur GitHub

Je cherche un moyen de convertir le javadocs de mon projet open source (généré dans Eclipse) en GitHub MarkDown, ou trouver une autre solution simple pour afficher ma documentation sur GitHub (timide d'ajouter simplement un répertoire docs). Existe-t-il une solution simple à cela? Puis-je simplement pointer le GitHubREADME.md dans mon répertoire docs? Y a-t-il quelque chose de plus élégant? J'ai rayé Google.

javagithubjavadocmarkdown
39
Phil

Je ne pense pas qu'il soit possible de créer un Javadoc utilisable avec MarkDown. La meilleure solution est probablement de valider le Javadoc que vous avez généré sur le gh-pages branche (ou dans le docs/ répertoire en fonction des paramètres de votre projet). Il sera disponible sur:

http://username.github.io/projectname

Voici un exemple de l'un de mes projets:

http://ebourg.github.io/jsign/apidocs/

31
Emmanuel Bourg

Actuellement, vous pouvez également héberger votre Javadoc avec Pages Github non seulement d'un gh-pages branche, mais directement à partir de /docs dossier dans votre branche master. Vous pouvez consulter la section d'aide sur ce sujet, ici (consultez également l'image ci-dessous).

enter image description here

De plus, il y a un projet sur Github qui cible une conversion de Javadoc en Markdown (ne l'ai pas encore essayé, laissant juste la référence).

21
acoelhosantos

NE PAS archiver Javadocs dans le contrôle de code source de votre projet

Surtout pas dans la branche master! J'ai suivi les autres réponses à cette question pendant environ un an avant de décider que c'était une très mauvaise idée. Pourquoi?

  1. Cela rendait trop difficile l'examen des différences. J'ai même fait un script (voir ci-dessous) pour mettre à jour uniquement les pages Javadoc qui ont considérablement changé, mais c'était toujours un gâchis.

  2. Cela a trompé les outils de refactorisation d'IntelliJ. J'ai juste essayé de changer .x () en .getX () et j'ai dû approuver/rejeter chaque "x" dans les Javadocs. J'ai peut-être oublié d'exclure le dossier dans IntelliJ, mais si jamais vous utilisez sed/grep/find sur votre projet, vous devez vous rappeler de l'exclure à chaque fois.

  3. Il ajoute un tas de données dans git qui ne devraient tout simplement pas être là, rendant potentiellement les commandes pull et clone plus longues ... POUR TOUJOURS! Même si vous "supprimez" le dossier par la suite, il est toujours stocké dans git.

Où les javadocs devraient-ils aller?

Il est probablement préférable de les publier sur votre site Web, ou AWS ou heroku. Si vous devez vérifier javadoc dans le contrôle de code source, créez un projet séparé juste pour Javadocs afin que vous n'ayez jamais besoin de regarder le diff. Vous pouvez suivre les réponses des autres pour savoir comment procéder.

"J'ai lu ton post, mais je le fais quand même"

Voici mon script pour mettre à jour moins de javadocs. Il copie uniquement les fichiers avec des modifications substantielles de target/apidocs dossier dans le docs/apidocs dossier. Il ajoute également de nouveaux fichiers et supprime ceux qui ne sont plus utilisés. Je pense que j'ai utilisé de mauvais noms, newfile et oldfile, mais ça marche. Je veux dire, ce n'était pas suffisant pour justifier la vérification de javadoc dans le contrôle de code source de mon projet, mais cela aide.

#!/usr/bin/env bash

# -I means ignore lines matching a regular expression
# -q means "quiet" - only tell whether files differ or not
# -r means "recursive" - explore subdirectories
# -N means "treat absent files as empty" which makes absent files show up in Quiet mode.
diff -I '<!-- Generated by javadoc ' \
     -I '<meta name="date" content="' \
     -I '<title>' \
     -I 'parent.document.title=' \
     -N \
     -qr \
     docs/apidocs/ target/apidocs/ > target/javadocPatch.txt

# Now read in the output file created by the previous command and
# Update only files that have substantial changes.
while read  ignore1 oldfile ignore2 newfile ignore3
do
  if [ ! -f "$oldfile" ]
  then
    echo "Added $oldfile"
    echo -n >$oldfile
    cp -fu $newfile $oldfile
  Elif [ ! -f "$newfile" ]
  then
    echo "Deleted $newfile"
    rm $newfile
  else
    echo "cp -fu $newfile $oldfile"
    cp -fu $newfile $oldfile
  fi
done < "target/javadocPatch.txt"
4
GlenPeterson

C'est peut-être un peu hors sujet, mais je pense que OP cherche un mécanisme pour rendre automatiquement javadoc disponible à mesure qu'une nouvelle version du projet est publiée.

Si tel est le cas, vous pouvez essayer: http://javadoc.io

Il s'agit d'un service gratuit hébergeant des javadocs pour un projet open source, prenant actuellement en charge maven central et bintray (jcenter).

Vous pouvez générer un lien vers la dernière version de votre projet. Par exemple, ce lien https://javadoc.io/doc/org.springframework/spring-core pointe toujours vers la dernière version de spring-core , qui est 5.2.0.RELEASE au moment où j'écris cette réponse.

Declaimer: je lance javadoc.io

1
Max