noveogroup/university-ios-presentations

iOS university presentations

Ветка gh-pages формируется автоматически после добавления изменений в master.

Создание лекции

1. создать в директории source/docs новый .md файл (и, по необходимости, соответствующую директорию для картинок)
2. в корневой директории запустить билд-скрипт: sh build.sh
3. Должны появиться .html-файлы (source/index.html и в директории docs). Их можно открывать в браузере - в них будут лекции. Если будут проблемы с отображением в хроме - в сафари должно работать (проблемы локальные, в итоге всё будет нормально и в хроме тоже)
4. чтобы добавить лекцию в список на главной странице, нужно добавить соответствующую строчку в source/docs/index.md (путь до лекции должен быть относительно корня)

Редактирование лекции

Чтобы отредактировать уже существующую лекцию, нужно редактировать соответствующий .md файл. Кроме него и, возможно, картинок, в папке не должно быть других изменений.

Важно! Не нужно редактировать .html-файлы с лекциями (кроме шаблонных) - все изменения будут потеряны при перегенерации. Эти файлы добавлены в .gitignore

Лекции нужно писать в формате Markdown, для примера синтаксиса можно посмотреть в уже созданные лекции в папке source/docs. В интернете множество страниц с описанием синтаксиса, например

Разделение слайдов происходит по символам ----. Можно делать слайды, перелистывающиеся по вертикали - например, для более подробного уточнения некоторых особенностей (Как в lecture_4.md). Разделитель вертикальных слайдов - --

Проведение лекции

Полезные сочетания клавиш здесь. В частности, стоит обратить внимание на speaker's mode - он позволяет вынести лекцию в отдельное окно некоторую метаинформацию.

Кроме того, можно воспользоваться заметками. Для этого можно в md-файлах добавить поля ^Note: в каждом слайде. Эти заметки будут не видны в презентации, но видны в speaker's режиме. Важно! Поскольку лекции публичные, по завершению лекции заметки будут доступны всем желающим (и видны в репозитории), нужно относиться к ним так же внимательно, как и к самим лекциям.

Экспорт лекций в pdf

• Открыть лекцию, добавить к адресу ?print-pdf, например: ...university-ios/docs/lecture_4.html?print-pdf
• распечатать в pdf (нажать ctrl+P и следовать инструкции)

Для автоматического обновления страницы

Чтобы не обновлять страницу руками после каждого изменения файла, можно воспользоваться grunt. Эта система поднимает локальный сервер, и следит за изменениями файлов, обновляя страницу.

Установить node.js (https://nodejs.org)

Установка необходимых компонентов:

sudo npm install -g grunt-cli
npm install

Запуск локального сервера:

grunt serve

Компиляция css-тем после изменения:

grunt css-themes

Как это работает?

Лекции построены на базе движка 'reveal.js'. Есть html-страница, на ней запускается reveal-скрипт, в качестве источника данных которого указываются markdown-файлы. Кроме того, можно подкладывать css-темы (например, тут использована тема engine/scc/theme/noveo.css).

Проблемной стороной данного подхода является то, что для каждой лекции нужен свой html-файл. Поэтому, было решено добавить файл-шаблон, и генерировать html-файлы на лету.

TODO: В дальнейшем планируется перенести генерацию в GitLab CI. Для этого нужно переписать CreateLecture.py в ruby (т.к. shared runner в gitlab.com не позволяют использовать python), либо создать специального runner-a (желательно, с соответствующим docker-контейнером). Для этого уже заготовлен .gitlab-ci.yml - но возможно, придётся что-то еще обновить.

GitHub+Travis плохо подходят для этих целей, т.к. GitHub требует, чтобы все исходники сайта с лекциями были закоммичены в репозиторий. Соответственно, нужно настраивать Travis для сборки и пушей в соответствующую ветку (и только в неё). Результат сборки неотделим от кода, это неправильно идеологически. Сейчас это настроено для ветки gh-pages