search

AndreyAkinshin / Russian-Phd-LaTeX-Dissertation-Template

LaTeX-template for russian Phd thesis
Creative Commons Attribution 4.0 International
1.33k stars 670 forks source link

Wiki #144

Open Lenchik opened 8 years ago

Lenchik commented 8 years ago

По следам 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 commented 8 years ago

Главной страницей считается файл с именем 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 commented 8 years ago

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

dustalov commented 8 years ago

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

dustalov commented 8 years ago

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

Lenchik commented 8 years ago

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

kostyfisik commented 8 years ago

Можно из 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 commented 8 years ago

Спасибо. Может быть, удастся как-то это автоматизировать с помощью 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 commented 8 years ago

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

timtonk commented 8 years ago

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

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

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

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

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

uralbash commented 8 years ago

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

timtonk commented 8 years ago

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

kostyfisik commented 8 years ago

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

uralbash commented 8 years ago

Обычно делают так, создают прямо в репе папку 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 commented 8 years ago

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

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

Lenchik commented 8 years ago

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

Lenchik commented 8 years ago

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

Lenchik commented 8 years ago

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