microcell (microcell) wrote,
microcell
microcell

Category:

Отображение JavaDoc в GitHub

Существует такая вещь как javadoc, которая помогает всем лентяем писать красивые (но, по большей части, бесполезные) каменты к своим программам. Вообще я считаю, что javadoc не есть good, поскольку мануал к серьёзной библиотеке не должен генерироваться непойми кем, но иногда, всё же, без него не обойтись особенно, если за написание комментариев вам не платят.

Существует другая вещь - GitHub Pages, которая позволяет вам запостить документацию к своему проекту. Сразу возникает вопрос - можно ли сочетать одно с другим? Не верьте тем пустобрёхам, которые скажут вам, что это невозможно, что нужно использовать *.md или что-то вроде. Они просто ламмеры не умеют читать мануалы. Сейчас я расскажу вам, как легко и просто отобразить страничку, сгенерированную JavaDoc в GitHub.

Прежде всего, предположим, что у вас уже есть git-репозиторий и сгенерированный javadoc-сайт, иначе у вас этого вопроса просто бы не возникло.

Прежде всего, следует клонировать ваш репозиторий в новую директорию. (Здесь и дальше выделеным шрифтом отмечено то, что вам придётся поменять под себя.)

$ git clone https://github.com/user/repository.git repository-doc



Имя для директории может быть любым, но лучше не делать его таким же, как имя самой репозитории. Я, лично, люблю добавлять к имени репозитори слово "-doc" но это на любителя. Далее следует перейти в новую директорию и создать новый бранч.

$ cd repository-doc
$ git checkout --orphan gh-pages



тут следует кое-что пояснить. Бранч gh-pages это ключевое имя для GitHub Pages и всё, что вы запостите в этом бранче, будет доступно в виде сайта. Ключевое слово --orphan означает именно то, что означает - вы создаёте бранч-сироту, без привязки к родительскому аккаунту. Естественно, вам не нужно постить там саму программу, поэтому исходники из нового бранча безжалостно стираются.

$ git rm -rf .



Теперь осталось только скопировать туда докуметацию javadoc (которая обычно находится в корне репозитория, в директории doc. Если у вас там её нет, то найдите её или сгенерируйте, не мне вас учить.

$ cp ../repository/doc/* * 



Вcё, осталось запостить новый бранч на гитхаб:

$ git add -r *
$ git commit -a -m "Commit documentation"
$ git push origin gh-pages



Будьте готовы к тому, что GitHub будет загружать вашу страничку в первый раз в течении где-то 10-15 минут. По истечении этого срока, ваша страничка будет доступна по адресу http://user.github.io/repository .

Тут есть ещё два момента, о которых следует упомянуть. Во-первых, сайт документации будет виден всегда, даже если ваш репозиторий - приватный. И, по этой же причине, доступ к нему будет через http, без каких-либо юзернеймов и паролей. Если же вас это, по какой-то причине, не устраивает, то гитхаб настоятельно рекоммендует вам обзавестись собственным сайтом и не морочить им головы.

Больще об этой технологии можно прочесть на страничке гитхаба.
Tags: github, java, javadoc, пособие по вкручиванию лампочек
Subscribe
  • Post a new comment

    Error

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.
  • 0 comments