Документация (Татарова, Шкуро, Ушаков, Пацеев)

[Molkree]

• Разработка шаблона документа на задачу Template #80
• Сбор документации по всем задачам Список задач без документации #132
• Интеграция документации в единый документ PDF

[Molkree]

1. Зачем вы ставите подсветку синтаксиса csharp для кода нашего языка?
2. Скрипт собирания в PDF уже есть? Пора бы уже делать.
   2a. Вот этот тег подсветки csharp поддерживается в сборке PDF вообще?

[Taally]

@Molkree

1. csharp для нашего языка можем и убрать, если скажешь, но там подсвечиваются ключевые слова, которые в основном совпадают с нашим языком.
2. скрипт - нет, есть библиотека pandoc, которая может собирать файлы markdown в один
   2а. да, поддерживается

[Molkree]

1. Подсветка для цикла for плохо отрабатывает.
2. Библиотека это круто, но вы собираетесь локально сгенерировать один раз PDF и загрузить? Я считаю, что генерация тоже должна быть в репозитории. Как минимум файл с инструкцией по генерации, а лучше генерировать новую PDF автоматически, если кто-то что-то меняет в документации.

[Taally]

1. Можем убрать, просто тогда он вообще не будет подсвечиваться, если это ок, то без проблем.
2. А зачем делать какую-то автоматическую генерацию, если это должно быть единичное действие, когда вся документация уже есть и остается ее только собрать? Это лишнее, мне кажется. И зачем инструкция, если (опять же) это единичное действие, когда все будет готово?
   Мы можем сделать тебе скрипт с собиранием всех файлов в один md-файл, но потом его тоже придется переводить в pdf с помощью pandoc, потому что это единственный нормально работающий способ (онлайн конвертеры из md в pdf делают это как-то криво), но оно точно надо? Выглядит как лишняя работа.
   Или можем написать инструкцию, как создать pdf из нескольких md-файлов с использованием pandoc

[Molkree]

1. Я не говорю, что прямо везде нужно убрать, оно действительно в большинстве случаев нормально подсвечивается, мб только в кусках, где есть циклы. Хотя хоть что-то это лучше, чем ничего :)
2. Нет, никакой лишней работы по сборке нескольких md в один не надо. Если непонятно зачем, то можете это расценивать как мою личную просьбу, просто интересно, как сделать такое :) там же не так уж и много, просто скажите, какие пакеты ставили, какие параметры для pandoc (я с ним немного знаком), не должно же это занять так много времени

[NikMozd]

Было бы неплохо, если бы вёлся список того, каких доков не хватает

[Ukolnir]

Чуть позже будет список тех задач, по которым нет доков. Полноты, правда, не гарантирую

[Taally]

Сделала генерацию одного общего md-файла на питоне (с заданием порядка файлов в отдельном текстовом файле, чтобы не переименовывать), и чтобы хотя бы на гитхабе было видно хорошо документацию (и чтобы для pandoc был правильный порядок секций без дополнительной мороки с переименовыванием). Но не могу победить Actions гитхаба, для питона всё устанавливается, но чтение/запись файла не получается сделать, есть какой-то способ, ты случайно не знаешь, @Molkree ?
Ну а если не автоматизировать, получается просто надо будет поправить при необходимости порядок глав (или добавить новые при появлении новых), и дальше как в инструкции: перевести файл в docx, добавить содержание, чтобы оно работало в pdf, и сохранить в pdf.

[Molkree]

@Taally, это всё в этой ветке происходит или ещё где-то? Что конкретно не выходит? Я там ничего не вижу связанного с GitHub Actions.

[Taally]

@Molkree не, с Actions я пока в отдельном репе экспериментировала, могу сюда добавить попытки (но там я пока даже не gen.py, а просто хоть что-то с записью в файл пыталась)

[Molkree]

Если ты про это, то могу предположить, что ты просто забыла тут кавычки экранировать, у тебя же строка в строке :)

[Taally]

@Molkree хах, действительно, спасибо) Но записывать в файл все равно не получается, теперь показывает, что всё ок, но файл не меняется. И с запуском питоновского файла он не хотел работать (писал что-то вроде permission denied, и на этот счет у меня ничего не гуглится, но не исключено, что я просто плохо гуглю)

[Molkree]

Хм, ну да, файл в репозитории не меняется. В пределах job он наверное всё же меняется, раз ошибок нет. Если хочется менять файлы в репозитории, то я про это писал вот тут немного, гуглить нужно в эту сторону (последний абзац про это).

[Taally]

@Molkree окей, спасибо, я читала, но надеялась, что хотя бы в существующий файл можно будет записать как-нибудь проще. Буду гуглить дальше