Показать JavaDocs на GitHub

Ответ 1

Я не думаю, что можно сделать полезный Javadoc с MarkDown. Лучшее решение, вероятно, состоит в том, чтобы зафиксировать Javadoc, сгенерированный вами на ветке gh-pages (или в каталоге docs/ в зависимости от настроек вашего проекта). Он будет доступен по адресу:

http://username.github.io/projectname

Вот пример из одного из моих проектов:

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

Ответ 2

В настоящее время вы также можете разместить Javadoc с помощью Github Pages не только с ветвью gh-pages, но и непосредственно из папки /docs в вашей ветке master, Вы можете проверить раздел справки по этой теме, здесь (также проверьте прикрепленное изображение ниже).

Кроме того, есть проект Github, который нацелен на преобразование Javadoc в Markdown (еще не пробовал, просто оставив ссылку).

Ответ 3

НЕ проверяйте Javadocs в системе контроля версий для вашего проекта

Особенно в ветку master! Я следовал за другими ответами на этот вопрос в течение года, прежде чем решил, что это действительно плохая идея. Почему?

1. Это делало его слишком сложным для просмотра различий. Я даже создал скрипт (см. ниже), чтобы обновлять только страницы Javadoc, которые существенно изменились, но это все еще был беспорядок.

2. Это обмануло инструменты рефакторинга IntelliJ. Я просто попытался изменить .x() на .getX() и должен был утвердить/отклонить каждый "x" в Javadocs. Может быть, я забыл исключить папку в IntelliJ, но если вы когда-либо используете sed/grep/find в своем проекте, вы должны не забывать исключать его каждый раз.

3. Он добавляет кучу данных в git, которых просто не должно быть, что потенциально заставляет команды pull и clone занимать больше времени... НАВСЕГДА! Даже если вы позже "удалите" папку, она все равно будет сохранена в git.

Куда пойти Javadocs?

Лучше всего публиковать их на своем веб-сайте, или в AWS, или в Heroku. Если вы должны включить Javadoc в систему управления версиями, создайте отдельный проект только для Javadoc, чтобы вам никогда не приходилось смотреть на diff. Вы можете следить за ответами других людей, чтобы узнать, как это сделать.

"Я читаю ваш пост, но все равно делаю это"

Здесь мой скрипт для обновления меньше Javadocs. Он только копирует файлы с существенными изменениями из папки target/apidocs в папку docs/apidocs. Он также добавляет новые файлы и удаляет больше не используемые. Я думаю, что использовал плохие имена, newfile и oldfile, но это работает. Я имею в виду, этого было недостаточно, чтобы оправдать включение javadoc в систему контроля версий моего проекта, но это помогает.

#!/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

Это может быть немного не по теме, но я считаю, что OP ищет механизм, позволяющий автоматически сделать Javadoc доступным при публикации новой версии проекта.

Если это так, то вы можете попробовать: http://javadoc.io

Это бесплатный сервис хостинга javadocs для проекта с открытым исходным кодом, в настоящее время поддерживающий maven central и bintray (jcenter).

Вы можете сгенерировать ссылку на последнюю версию вашего проекта. Например, эта ссылка https://javadoc.io/doc/org.springframework/spring-core всегда указывает на последнюю версию Spring-Core, которая является 5.2.0. ПОДАВЛЯЙТЕ в то время, когда я пишу этот ответ.

Заявитель: я запускаю javadoc.io