В чём писать документацию? (v2)
если я правильно понял вопрос, то можно использовать css для изменения стиля.
А где его взять, этот CSS? У меня совсем плохо с чувством юзабилити.
можно в качестве первого приближения попробовать натянуть bootstrap, ну или поискать странички с документацией, которая пристойно выглядит, и посмотреть, что оттуда можно адаптировать.
короче, это работа, которую кто-то должен сделать.
короче, это работа, которую кто-то должен сделать.
docbook ?
В я его критиковал, но там дело касалось технической документации, а не программерской
В я его критиковал, но там дело касалось технической документации, а не программерской
docbook ?Аскидок и так генерирует docbook как промежуточный результат. Так что проблема с некрасивыми стилями остаётся силе. У докбука они такие же
А где его взять, этот CSS? У меня совсем плохо с чувством юзабилити.CSS сложно подобрать будучи 0 в нем, надо стырить с похожей на то, что нужно, страницы.
Кстати подсветку синтаксиса я так понимаю счас можно делать только клиент-сайд на джаваскрипте. а видел кто-нить генераторы, чтоб подсвечивали на html и css?
http://pygments.org/languages/ - это же классика из классики. Оффлайн, без js, поддерживает кучу языков
в asciidoc есть встроенная подсветка кода
у markdown есть расширение для нового тега {code}:
http://marketplace.atlassian.com/plugins/jira.plugin.syntax...
а так тебе правильно говорят - пили CSS как тебе хочется чтобы твой html выглядел.
у markdown есть расширение для нового тега {code}:
http://marketplace.atlassian.com/plugins/jira.plugin.syntax...
а так тебе правильно говорят - пили CSS как тебе хочется чтобы твой html выглядел.
Я попробовал asciidoc и markdown. Синтаксис обоих вполне устраивает.В markdown нельзя ссылаться на другие страницы. Только как URL их вставлять. Так что имхо для документации лучше asciidoc всё-таки.
CSS по вкусу можно спиздить здесь например.
Мы фигачим в doxygen, как бы приятно что и комменты к конкретным методам подтягиваются, и можно просто пойти и написать кусок документации в how_to_blah.hpp который никто не инклюдит. И, главное, что изменения в документации трекаются гитом.
Стиль получающегося HTML приемлемый, на мой вкус.
Есть некоторые проблемы, например, мы куда-то потеряли возможность указать какой именно язык программирования надо подсвечивать в code block, и никто не знает чо ваще и как. Может, это мы тупые, конечно — но раньше же работало, ёпта!
Стиль получающегося HTML приемлемый, на мой вкус.
Есть некоторые проблемы, например, мы куда-то потеряли возможность указать какой именно язык программирования надо подсвечивать в code block, и никто не знает чо ваще и как. Может, это мы тупые, конечно — но раньше же работало, ёпта!
Вести с полей.
Для asciidoc синтаксиса существует новый современный процессор — asciidoctor:
Я заморочился и сделал тестовый документ со стандартными элементами, чтобы можно было выбрать стиль по вкусу. Вот так выглядит дефолтный стиль asciidoctor, примененный к тестовому документу. Там же демонстрация и всех остальных стилей.
Для asciidoc синтаксиса существует новый современный процессор — asciidoctor:
- Синтаксис на 95% совпадает с оригинальным asciidoc. Отличия только в неоднозначных моментах синтаксиса + добавлены плюшки.
- Конвертация происходит сразу в целевой формат, минуя docbook. Docbook также поддерживается как в качестве целевого формата.
- Структура HTML совпадает на 95% с оригинальным asciidoc, включая названия стилей. Поэтому одни и те же CSS файлы можно использовать в обоих процессорах.
- Asciidoctor идет в комплекте с современным стилем (не считая того, что от страдает гигантизмом). С гитхаба можно скачать еще с десяток стилей.
Я заморочился и сделал тестовый документ со стандартными элементами, чтобы можно было выбрать стиль по вкусу. Вот так выглядит дефолтный стиль asciidoctor, примененный к тестовому документу. Там же демонстрация и всех остальных стилей.
Там же демонстрация и всех остальных стилей.гитхаб - лучший.
Riak - ничё.
всё остальное - вырвиглазный пиздец.
ну может ещё rocket-panda сойдёт.
а вообще спасибо - хорошая работа.
Еще раз заморочился и написал свою тему. Ну то есть как свою — скомпилировал из нравящихся мне стилей и довел до ума. 
Оставить комментарий
Garryss
У меня есть потребность писать программерскую документацию и конертировать ее в HTML.рекомендует asciidoc. Я попробовал asciidoc и markdown. Синтаксис обоих вполне устраивает. Проблема в том, что при генерации в HTML стиль этого самого HTML оставляет желать, мягко говоря, лучшего. Подсветка кода — это вообще полный П. А хочется, чтобы было красиво и аккуратно, как на гитхабе или в WP-блогах.
Есть какие-нибудь советы на этот счет?