В чëм сейчас пишут документацию?

Question

[vladimirbobkov7]

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

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

Разработчиков - 10 человек, работают под Windows, Linux.

Начали работать со Sphinx, но крайне напрягает, что
0) сложная настройка;
1) нет универсального WYSIWIG редактора
1) результат зависит от платформы;
2) PDF и HTML версии документации сильно отличаются.

Можете посоветовать что-то универсальное, кроссплатформенное?

Comments

[alexsavochkin]

Попробуйте гостдаун. Он заточен под научно-технические тексты, конвертирует в ПДФ, а маркдаун можно собрать и в хтмл.

Answer 1

[Василий Банников]

Я бы посмотрел в сторону latex, если формул прям много и нужна на выходе адекватная пдфка.

Схемы - уже зависит от характера схем. Если это какие-то архитектурные диаграммы и блок-схемы с описанием алгоритмов, то я бы взял plantuml и mermaid.

А про wysiwig бы забыл как страшный сон.

Comments

[mayton2019]

Да. Весь научный мир лабает статьи и монографии в Лакексе. Вот насчет схем я тут не уверен.
Скороее всего сборка подобной документации должна предоставлять на выходе некий продукт.
Тоесть как исходный код - продукт так и документация тоже должна быть продуктом.
И Pipelines которые собирают доки должны уметь генерировать еще и чертежи и схемы
и графики. И внедрять их в PDF. Как картинки. Или как всякие там векторные картинки.

Насчет HTML я не уверен. Никогда не удавалось управлять версткой настолько точно чтоб
получить размеры как в PDF. Поэтому я-бы просто не ставил такую цель.

[vladimirbobkov7]

Понятно, что разработчики сего кода, как люди близкие к науке, владеют LaTeX' ом.

Но
- Sphinx прельстил именно (почти)свободным использованием всавок LaTeX - и это, похоже, единственное, что дает почти одинаковый результат на разных платформах - ломается всё как раз из-за микса RST и latex;
- Что делать с HTML?

[Adamos]

mayton2019,

Весь научный мир лабает статьи и монографии в Лакексе.

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

[mayton2019]

В Офисе тоже можно лабать. Только с дизайном математических формул там - неудобно. Надо миллион движений мышко сделать. В противоположность в Latex ( если чел опытный ) то наберет формулу с одного раза. И искать и правки делать потом удобнее. И даже в git мастер оригинал положить можно.

[CityCat4]

mayton2019, Я тоже за Latex - если там реальнэ много формул и всякой зубодробительной математики (которую я не понимаю и не люблю). Поэтому тут я +100500
Одно замечание от граммар-наци - не Латекс - нечто, связанное с резинотехническими изделиями или порно, а именно Латех - набор макросов для текстового процессора ТеХ

[shurshur]

Если кто не знает, TeX по мнению его автора надо читать как ГРЕЧЕСКОЕ слово.

[mayton2019]

CityCat4, согласен. Я бываю невежда в словах. Тут еще от окружения зависит. Как то работали мы с одним хедж-фондом. Архитектор был очень оригинальный дядечка. Любил каламбуры. Вместо слова "скобочка" он говорил - "скобАчка" (ударение на другой слог). И я заразился этой заразой.

[CityCat4]

mayton2019, Бывает. У меня начальник обычно говорит не "какая-то фигня", а "какая-то шляпа". И ко мне тоже прилипло это выражение, блин :D

[Saboteur]

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

Answer 2

[uvelichitel]

Мне полюбился asciidoc. Последнее время почти весь свой текст в нём пишу. Конкретная реализация https://asciidoctor.org/ Есть поддержка формул (AsciiMath и TeX) и диаграмм (plantuml и mermaid) Можно вставлять куски TeX. При рендеринге в PDF или PS очень приличная типографика.
Академисты пишут конечно на latex, но есть недостатки. latex -- инструмент вёрстки, семантической разметки практически нет и неудобо-человеко-читаемо.
Обязательно посмотрите на конвертер pandoc https://pandoc.org/. Можно писать в чём попало и сконвертировать во что заблагорассудится)