[dxp 175]

Всем привет!

Проект, наконец, обзавёлся похожим на настоящий сайтом: https://scmrtos.github.io.

Сайт поддерживает два языка (English/Русский). 

Основной причиной появления сайта стал перевод документации в онлайн формат, как более удобный и оперативный, и которая более актуальна, чем pdf варианты (они давно не обновлялись и скорее всего постепенно отомрут -- останутся только для истории).

Сайт создан генератором статических сайтов MkDocs, исходники этого проекта лежат по ссылке: https://github.com/scmrtos/project-site. Сами тексты там в формате markdown (файлы с расширением md), доступны для чтения без дополнительных инструментов.

[HardEgor 153]

35 минут назад, dxp сказал:

чем pdf варианты (они давно не обновлялись и скорее всего постепенно отомрут -- останутся только для истории)

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

[dxp 175]

2 часа назад, HardEgor сказал:

Очень плохо.

Этот сайт можно целиком скачать, он смешного размера, там ни одной картинки нет, только текст. Кроме того, в отличие от pdf, этот вариант прекрасно читается на телефоне (попробуйте), можно даже просто читать без напрягов, лёжа на диване, для аварийного случая точно пойдёт.

PDF хорош для твёрдой копии (собственно, он и есть твёрдая копия). Многие элементы форматирования на этот формат плохо ложатся -- например, длинные листинги, рвутся страницами, что-то по ширине не пролазит (формат страницы). Очень много ручной работы -- те же листинги, если текстом, они без подсветки, вид намного хуже. На онлайн доку можно ссылку кинуть прямо сюда, а PDF надо либо цитату копировать, либо текстом описывать местоположение (стр. 25, 3-й абзац снизу). Сам процесс открывания более тяжеловесный и неудобный.

Ну, и поддерживать этот формат намного тяжелее. Во всяком случае, для меня: исходник в odt формате (ранее был doc), это под контроль версий не ложится  нормально (трудно отслеживать изменения), структура документа довольно тяжеловесная -- множество нумерованных заголовков, куча закладок, перекрёстных ссылок, автоматическая нумерация, кастомные стили, регулярно что-то слетало, ломалось, обнаруживаешь не сразу, чинишь. А LaTeX я так и ниасилил (мотивации не хватило). 

 

[makc 369]

Очепятка:

21 час назад, dxp сказал:

Проект, наконец, обзавёлся похожим на настоящий сайтом: https://scmrtos.github.io.

Я правильно понимаю, что исходники текстов в универсальном формате пока недоступны? Может быть их выложить на тот же гитхаб, чтобы желающие могли скачать и транслировать, например, в pdf?

[dxp 175]

24 минуты назад, makc сказал:

Очепятка:

О, а где это вы увидели? Можно ссылку, я такого не нахожу (это фрагмент какой-то рабочей версии, которой уже нет)?

24 минуты назад, makc сказал:

Я правильно понимаю, что исходники текстов в универсальном формате пока недоступны?

Всё доступно, лежит там же, где и все репозитории проекта: https://github.com/scmrtos/project-site. Основные тексты в markdown формате, читаются без специальных  средств. Не думал, что это кому-то интересно, поэтому специально упоминать не стал.

24 минуты назад, makc сказал:

чтобы желающие могли скачать и транслировать, например, в pdf?

Я, кстати, пробовал -- там для mkdocs есть несколько плагинов для этого. Но большинство выдают корявый результат. Один какой-то получился почти нормальным, но он по-файлово выдавал (каждый md -> pdf), и там ссылки между разделами не работают, не стал его продвигать. В целом, наверное при определённых усилиях можно получить годный результат, но меня на это уже не хватило.

[makc 369]

Только что, dxp сказал:

О, а где это вы увидели? Можно ссылку, я такого не нахожу (это фрагмент какой-то рабочей версии, которой уже нет)?

На корневой странице репозитория в гитхабе.

1 минуту назад, dxp сказал:

Всё доступно, лежит там же, где и все репозитории проекта: https://github.com/scmrtos/project-site. Основные тексты в markdown формате, читаются без специальных  средств. Не думал, что это кому-то интересно, поэтому специально упоминать не стал.

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

1 минуту назад, dxp сказал:

Я, кстати, пробовал -- там для mkdocs есть несколько плагинов для этого. Но большинство выдают корявый результат. Один какой-то получился почти нормальным, но он по-файлово выдавал (каждый md -> pdf), и там ссылки между разделами не работают, не стал его продвигать. В целом, наверное при определённых усилиях можно получить годный результат, но меня на неё уже не хватило.

pandoc пробовали?

[dxp 175]

2 минуты назад, makc сказал:

На корневой странице репозитория в гитхабе.

А, в README.md, я думал, на сабжевом сайте. Исправил на ветке develop. https://github.com/scmrtos/scmrtos/blob/develop/README.md

8 минут назад, makc сказал:

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

Добавил ссылку на исходники в тему.

8 минут назад, makc сказал:

pandoc пробовали?

Нет, только штатные средства (плагины). Не владею этой технологией.

[makc 369]

8 минут назад, dxp сказал:

Нет, только штатные средства (плагины). Не владею этой технологией.

https://github.com/alexandre-perrin/mkdocs-pandoc-plugin

[dxp 175]

1 минуту назад, makc сказал:

https://github.com/alexandre-perrin/mkdocs-pandoc-plugin

Хм, почему-то мне поиском этот не попался (ИИ, кстати, советовали там в полный рост). Попробую, спасибо!

[dxp 175]

24 минуты назад, dxp сказал:

Попробую, спасибо!

Накатил плагин. Этого оказалось мало -- он только умеет как-то звать сам pandoc. pandoc пришлось ставить отдельно. К нему потом ещё пачку довольно немелких либ. В итоге с ходу не получилось. Во-первых, он не один док генерит (хотя, может, это как-то рулится, не вникал), а на каждый md. Во-вторых, доки местами битые -- где-то он заголовки не всосал, где-то admonitions, на ссылки ругался варнингами, что, де, нету на них линков, хотя на основной версии (веб) всё работает, я проверял. На прошлые попытки получить нормальный pdf я потратил в общей сложности порядка дня. В это что-то погружаться не хочется (во всяком случае сейчас, уже порядком "объелся" я этой темы).

[makc 369]

3 часа назад, dxp сказал:

В это что-то погружаться не хочется (во всяком случае сейчас, уже порядком "объелся" я этой темы).

Тогда, если не сложно, сделайте последний эксперимент с https://github.com/HaoLiuHust/mkdocs-mk2pdf-plugin

Там в описании есть флаги:
 

Цитата

combined

Setting this to true will combine all pages into a single PDF file. All download links will point to this file. Default is false.

combined_output_path
This option allows you to use a different destination for the combined PDF file. Has no effect when combined is set to false. Default is pdf/combined.pdf.

Судя по ним на выходе должно получиться ровно то, что нужно. 🤔

[dxp 175]

1 час назад, makc сказал:

Тогда, если не сложно, сделайте последний эксперимент с https://github.com/HaoLiuHust/mkdocs-mk2pdf-plugin

Этот даже не ставится. В интернетах говорят, что это старый заброшенный плагин, на новых питонах (у меня 3.12) оно не работает (там используется архаичный способ установки с помощью setup.py). Можно, конечно, повозиться, создать новое виртуальное окружение, установить в него старый питон... Но не вижу смысла. Нет ни уверенности, что получится, ни надежды, что этот проект будет жить.

До этого я перепробовал их кучу:

• mkdocs-exporter
• mkdocs-pdf-export-plugin
• mkdocs-with-pdf
• mkdocs-print-site-plugin

Один из самых популярных mkdocs-with-pdf, рожает pdf со съехавшими заголовками -- некоторые заголовки наползают на текст, листинги (теги ```) разломаны -- в одну строку выдаёт и т.п. 

mkdocs-pdf-export-plugin в процессе конвертации выдавал кучу ошибок, в итоге родил файл, у которого одни начальные страницы разделов.

Лучше всех себя показал mkdocs-print-site-plugin, он по крайей мере выдал что-то похожее на правду, но он увлекается нумерацией, и там она безобразная: Print Site - scmRTOS.pdf. Кстати, этот выглядит прилично, плагаю, потому, что его рендерил браузер, плагин там только сборку из отдельных страниц в одну делает, как я понял. Но сборка получилась так себе -- нумерация дебильная, ненужная, ссылки не работают, даже сноски. 

И тут нет автоматизации -- этот файл надо руками из браузера добывать. И да, там только русскоязычный вариант получается, англоязычный не даёт. 

Полагаю, что проблемы лезут в том числе из-за темы readthedocs. Большинство плагинов ориентированы на тему material. Если выбрать эту тему, то тот же mkdocs-with-pdf ведёт себя намного лучше, уже заголовки не наползают, но некоторые элементы -- например, списки, выводятся безобразно мелким шрифтом. А листинги всё равно вот такие:

И файлы сгенерила не до конца, до половины где-то. Ругани никакой фатальной в консоли при этом не было.

В общем, я думаю, что не нужно мучиться и пытаться автоматом из mkdocs это вытащить. Надо это делать как-то отдельно -- тем же pandoc, создать для него скрипт (или что там у него), скормить ему исходники и рожать из них напрямую. Если это в принципе работает, то дело в шляпе. Остаётся, правда, ещё одна принципиальная проблема: не всё форматирование хорошо ложится на формат страниц твёрдой копии: полно висячих строк и, что хуже, висячих заголовков, разорванные листинги и т.п. Когда исходник doc/odt/tex, за этим можно как-то следить, чтобы тул автоматом это исправлял. Можно ли, например, pandoc настроить на это, хз.

Ну, а MkDocs -- генератор сайтов, и с этим он справляется хорошо. Генерить PDF из него получается не очень -- весьма мешают настройки темы, например. Может скрипты или другие плагины. Бороться с этим непродуктивно и бессмысленно.

 

 

[HardEgor 153]

19 часов назад, dxp сказал:

Этот сайт можно целиком скачать

Да мне в общем-то важен принцип - можно скачать и открыть один файл. Самый понятный и доступный формат - Адоб ридер. Сейчас он конечно стрёмный стал, но у меня 9-й ставится по умолчанию  на всех компах, вместе с Far и еще десятком утилит.

[dxp 175]

Предпринята попытка создать pdf версии. Результат на своём обычном месте (прежние версии перемещены в папку attic, там же по ссылке видно). Ссылка на pdf есть на первой странице сайта.

Документы созданы из тех же markdown исходников, что и сайт, по сути они дублируют содержимое разделов сайта.

Как и предполагалось, чтобы получить красивый и удобный pdf, никакой автоматической генерации недостаточно -- возможно, такое работает для каких-то простых случаев, в чём сомневаюсь, но для чего-то сколько-нибудь сложного (в смысле элементов оформления) получается фигня. Вот и в этом случае пришлось изрядно повозиться с pandoc/xelatex.

Сборка pdf осуществляется с помощью скриптов, они лежат в репозитории проекта документации (ссылка есть в первом сообщении этой темы). Для сборки одних этих скриптов недостаточно, нужно установить немало софта (сам pandoc, texlive, кучу расширений через pip, лучше всё это делать в виртуальном окружении python, чтобы не сломать что-нить в системе).

[AHTOXA 25]

Не забудь уточнить, что в создании pdf-документации неоценимую помощь оказали товарищи Грок и Дипсик 🙂. Ну и немножко я)