Wiki

[Lenchik]

По следам https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/commit/112b54a0dd6898a2c54412dd9b749b5062140137#commitcomment-18346256, https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/issues/123#issuecomment-234485505 и https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/pull/142#issuecomment-234378721

Суть идеи: большую часть документации положить в раздел wiki, может быть даеж, чтобы автоматически преобразовывалась в pdf и в релизы шла. @dustalov, на примере https://github.com/mtsar/mtsar/wiki, как там определяется какой файл главный, какие связи между ними? Как делать такое же меню как справа? Есть где справочник по интересным фишкам вики? Прям очень круто выглядит.

Какую нам структуру лучше сделать?

[dustalov]

Главной страницей считается файл с именем Home.md. Общий подвал для всех страниц задаётся в файле _Footer.md. Ссылки между страницами делаются в стиле MediaWiki, например [[Hello World]] сгенерирует корректную ссылку на страницу Hello-World.md.

Меню справа (сайдбар) генерируется автоматически путём перечисления всех имеющихся страниц в алфавитном порядке. Некоторых это не устраивает, тогда пишется собственный _Sidebar.md, например: https://github.com/google/guice/wiki.

Все wiki представлены в виде обычных репозиториев: git@github.com:<user>/<repo>.wiki.git. Чтобы загрузить картинку, нужно склонировать репозиторий и в обычном порядке добавить туда нужные файлы. При этом файл с картинкой не попадёт в автоматическое меню, но будет доступен по ссылке https://github.com/<user>/<repo>/wiki/<filename>.

В качестве первого шага можно переместить туда все имеющиеся файлы с документацией. GitHub предоставляет достаточно подробные инструкции: https://guides.github.com/features/wikis/.

[Lenchik]

https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/wiki - посмотрим. что будет получаться. Интересно, она всеми редактируема или там тоже пуллреквесты имеют место?

[dustalov]

PR не предусмотрены. Редактировать могут все, если этого не запретить в настройках: https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/settings.

[dustalov]

Идея по поводу wiki, не связанная с ней: ссылки на справочные материалы в README сделать ссылками на неё.

[Lenchik]

Удобство того, что вся документация в репозитории в том, что можно сохранить репозиторий в архив и уехать с ним в автономное от интернета пребывание. Разбираться с git и клонированием для этого не надо. Очень велик шанс, что всё будет работать, а проблемы, если будут, решены будут в результате прочтения документации. Утащить в этом же архиве вики - нельзя.

[kostyfisik]

Можно из wiki делать pdf и класть в репу. Гугел выдаёт несколько вариантов, например вот https://github.com/jobisoft/wikidoc вот http://mountainbikesandtrombones.blogspot.ru/2014/07/how-to-export-github-wiki-to-pdfs-andor.html вот https://gist.github.com/alexeyismirnov/85cdf7b1e9aea4d3494b

В общем для желающих есть возможность изучить вопрос....

[Lenchik]

Спасибо. Может быть, удастся как-то это автоматизировать с помощью python, Travis и submodule из гита. http://blog.terryburton.co.uk/2015/02/20/Creating-PDF-Documentation-From-a-GitHub-Wiki-Using-Pandoc.html http://stackoverflow.com/questions/15674064/github-submodule-access-rights-travis-ci

Некоторое время, я считаю, пусть посуществуют две документации - то что уже есть в репе (обновлять будем при крайней необходимости) и новая, пополняемая, в вики.

[timtonk]

md для локальной доки, КМК, не очень-то подходящий выбор

[timtonk]

Задача, вообще говоря, не очень тривиальная. Автоматизация билда через Travis - опасное дело. Нужен и доступ причастных к репе для настройки, нужно очень правильно креды настраивать, чтобы он мог закомитить билд внутрь. Изменения в структуре проекта нужно будет обязательно применять и в скрипт трависа. Естественно, об этом легко забыть.

Возможный вариант - через релизы. Поднять всё это вот на трависе, но деплоить не в репу, а в релизную область. Но и тут проблема - оно работает только для тегов. Нет тега - нет релиза - нет доков. Забудет кто-нибудь указать тег при обновлении вики и всё, приплыли.

Другой вопрос - что является триггером? Если изменения будут комититься в .wiki репу, то все хорошо, релизы через ci сойдут. Но если это будет редактирование через web, то у меня очень большие сомнения, что травис вообще вызовется. Итого опять - устаревшие доки.

В общем, я бы скорее подумал над простеньким скриптом в master, который сменит ветку, конвертнет вику в нормальный формат и вернётся назад. Но и тут минусы - надо ставить дополнительное ПО. На линуксе может ещё и норм, но на винде могут быть проблемы.

Может, ну его...

[uralbash]

Мне кажется sphinx-doc и readthedocs.io решает все выше писанные проблемы

[timtonk]

Так исходная проблема остаётся - нет скомпиленной документации локально. Есть только вики в сети и бранч с md.

[kostyfisik]

RTD хорошая идея. Решает вопрос генерации (автоматической) PDF из пачки MD. Ну и наверное у них можно хранить исходник на github (Wiki?) Т.е. будет синхронная документация и там, и там. К релизу всё равно pdf с шаблоном делаются в ручную во всех вариантах, можно туда же прикладывать и готовый pdf с доками.

[uralbash]

Обычно делают так, создают прямо в репе папку docs в ней документация в разметке rst сгенерированная системой sphinx-doc. ReadTheDocs умеет после каждого коммита пересобирать документацию, также можно там выставлять версии для конкретного коммита или ветки. Вот пример http://docs.pylonsproject.org/projects/pyramid/en/latest/ там же можно скачать pdf, epub итд. Для редактирования есть в правом верхнем углу кнопка edit me on github, по нажатию которой попадаешь на страницу https://github.com/Pylons/pyramid/blob/1.7-branch/docs/index.rst , которую можно отредактировать на гитхабе. Но лучше править локально у себя на компе.

[Lenchik]

К релизу всё равно pdf с шаблоном делаются в ручную во всех вариантах, можно туда же прикладывать и готовый pdf с доками.

Это тоже желательно автоматизировать. Не знаю только как. Docker или Vagrant сервис какой-нибудь, а может и Travis-CI сможет, чтобы запускался для каждой пдфки определенный набор компиляторов и опций. Это явно для отдельного обсуждения в отдельном issue (скорее всего, в #123).

[Lenchik]

Вот на этом что-то придумать? https://developer.github.com/webhooks/

[Lenchik]

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

[Lenchik]

https://github.com/GitbookIO/gitbook - вот это как-то автоматически задействовать, может быть? Хотя, что-то не понял, можно ли автоматизированно конвертировать.