Comments 19
В контексте данной статьи следовало бы также упомянуть reStructuredText.
ReST без sphinx рассматривать смысла не имеет. Sphinx же имеет множество возможностей, включая конвертацию форматов, и очень расширяем: вы вполне можете даже добавить поддержку не-ReST формата, если очень нужно (к примеру, есть дополнения для взятия информации из XML файла от DOxygen), или немного подправить результат, выдаваемый autodoc. Я сам писал код, который делает man странички из кода, использующего argparse.
Правда, значительная часть встроенных возможностей заточена под Python, но из-за расширяемости можно приспособить sphinx для чего угодно.
Правда, значительная часть встроенных возможностей заточена под Python, но из-за расширяемости можно приспособить sphinx для чего угодно.
Никак не могу себя заставить воспринимать и писать markdown формат. Он явно сделан для программистов и, мне кажется, непрограммистам так же тяжело его понять и принять. HTML кажется проще.
Честно говоря, вообще не согласен. У меня есть опыт перевода разного рода документации на маркдаун. При чем тех людей, которые никогда не были программистами. И они вполне себе освоились. И уж это точно проще, чем писать тэги html.
Если интересно, вот моя заметка по этому поводу: Вы все еще пишете ТЗ в Word? — Тогда мы идем к Вам!
Если интересно, вот моя заметка по этому поводу: Вы все еще пишете ТЗ в Word? — Тогда мы идем к Вам!
MarkDown — формат документирования систем в системе контроля версий Git.Bullshit. git использует asciidoc (см. github.com/git/git/blob/master/Documentation/git.txt, например).
Веб-портал системы Git github.org так же способен показывать документы в разметке Markdown в пригодном для чтения в браузере виде.Bullshit. GitHub ни пол раза не портал, не является официальным сайтом git'а, поддерживает не только markdown, но и rst, textile, asciidoc и кучу остального: см. github.com/github/markup.
Да уж, Грубера [https://daringfireball.net/projects/markdown/syntax] можно было бы упомянуть.
Но, справедливости ради, полноценно github поддерживает только их маркдаун с блекджеком. Если речь не только про README, а про комментарии и прочее.
Но, справедливости ради, полноценно github поддерживает только их маркдаун с блекджеком. Если речь не только про README, а про комментарии и прочее.
Насчет документации для git ошибся, согласен.
Дословно портал — красивый вход.
В ИТ-контексте — (общедоступный узел компьютерной сети) portal (https://slovari.yandex.ru/портал/ru-en/informatics)
Github интегрирован с git, так как «код проектов можно не только скопировать через Git, но и скачать в виде обычных архивов с сайта».
Вики называет github веб-сервисом и «графическим интерфейсом» git ru.wikipedia.org/wiki/Git#.D0.A4.D1.80.D0.BE.D0.BD.D1.82.D0.B5.D0.BD.D0.B4.D1.8B_.D0.B4.D0.BB.D1.8F_.D0.B2.D0.B5.D0.B1.
Так что «о терминах не спорят, о них договариваются».
Насчет markdown в github я и не утверждал, что «только» его поддерживает, это был один из примеров поддержки формата.
Дословно портал — красивый вход.
В ИТ-контексте — (общедоступный узел компьютерной сети) portal (https://slovari.yandex.ru/портал/ru-en/informatics)
Github интегрирован с git, так как «код проектов можно не только скопировать через Git, но и скачать в виде обычных архивов с сайта».
Вики называет github веб-сервисом и «графическим интерфейсом» git ru.wikipedia.org/wiki/Git#.D0.A4.D1.80.D0.BE.D0.BD.D1.82.D0.B5.D0.BD.D0.B4.D1.8B_.D0.B4.D0.BB.D1.8F_.D0.B2.D0.B5.D0.B1.
Так что «о терминах не спорят, о них договариваются».
Насчет markdown в github я и не утверждал, что «только» его поддерживает, это был один из примеров поддержки формата.
Да, как-то много очень неприятных ляпов в заметке. Это расстраивает.
Для DocBook раньше был ещё редактор Syntext Serna с бесплатной версией. Даже пост на Хабре был про него.
Недавно с удивлением обнаружил, что нет редактора больше. Похоже, компанию купили. На ребрендированный редактор даже посмотреть нельзя, если ты не корпоративный заказчик…
Старая версия тут ещё лежит.
Недавно с удивлением обнаружил, что нет редактора больше. Похоже, компанию купили. На ребрендированный редактор даже посмотреть нельзя, если ты не корпоративный заказчик…
Старая версия тут ещё лежит.
Да, к сожалению, ключевое слово — «был».
Но даже и тот что был, не поддерживал редактирование исходного текста xml docbook, а только визуально в редакторе.
Поскольку схема docbook довольно большая, то и поддержка в serna оказалась неполной.
Именно поэтому выбор пал на универсальный xml-редактор с встроенной поддержкой преобразований.
Но даже и тот что был, не поддерживал редактирование исходного текста xml docbook, а только визуально в редакторе.
Поскольку схема docbook довольно большая, то и поддержка в serna оказалась неполной.
Именно поэтому выбор пал на универсальный xml-редактор с встроенной поддержкой преобразований.
Может кто подскажет. Используя подобные языки разметки, типа md или rst, возможно ли затем:
1) Выводить на печать с пронумерованными страницами и оглавлением, в котором будут прописаны номера страниц.
2) Генерировать нормально выглядящий PDF, с нормальными шрифтами и с требованиями из пункта 1?
Пока у нас всё делается в ворде. И PDF он выводит отличный, и печатает с номерами страниц и оглавлением. Но хотелось бы отойти от него.
Я ковырялся довольно долго с reStructuredText, точнее со Sphinx, но PDF выходил отвратный (генерил через Latex, а rst2pdf коряво работает).
1) Выводить на печать с пронумерованными страницами и оглавлением, в котором будут прописаны номера страниц.
2) Генерировать нормально выглядящий PDF, с нормальными шрифтами и с требованиями из пункта 1?
Пока у нас всё делается в ворде. И PDF он выводит отличный, и печатает с номерами страниц и оглавлением. Но хотелось бы отойти от него.
Я ковырялся довольно долго с reStructuredText, точнее со Sphinx, но PDF выходил отвратный (генерил через Latex, а rst2pdf коряво работает).
А, ну и колонтитулы нужны.
Присмотритесь к этому сервису www.gitbook.com/.Тут вот можно почитать подробней github.com/GitbookIO/gitbook о «внутренних» составляющих.
Если кратко, то можно создавать репозитории и работать через git, или же все редактировать прямо в браузере. На выходе получается отличный pdf, mobi, epub или просто html. Вот пример gitbookio.gitbooks.io/markdown/.
Из тех примеров что видел — нигде не заметил нумерации страниц, но думаю что это дело только поправимо. Pdf же генерируется весьма сносный.
Если кратко, то можно создавать репозитории и работать через git, или же все редактировать прямо в браузере. На выходе получается отличный pdf, mobi, epub или просто html. Вот пример gitbookio.gitbooks.io/markdown/.
Из тех примеров что видел — нигде не заметил нумерации страниц, но думаю что это дело только поправимо. Pdf же генерируется весьма сносный.
Да я тут подумал и понял, что Tex мне полностью подходит. В любом случае, спасибо, интересный сервис.
Если вам подходит TeX, то это просто замечательно. Очень мощный и гибкий инструмент, мне лично очень нравится им пользоваться.
Но к сожалению не все так думаю. Очень многие люди бегут от TeX-а как от огня, что возможно и правильно — ибо у них нет каких-то «специализированных» запросов и им достаточно иметь WYSIWYG для редактирования текста.
Рад что вам понравился сервис.
Но к сожалению не все так думаю. Очень многие люди бегут от TeX-а как от огня, что возможно и правильно — ибо у них нет каких-то «специализированных» запросов и им достаточно иметь WYSIWYG для редактирования текста.
Рад что вам понравился сервис.
Мои опыты показали, что с этим хорошо справляется именно docbook+XEP (FOP)
Привет из 2019 года. В наше счастливое время уже есть средство для оформления Markdown стилями ГОСТ. Оно называется GOSTdown:
gitlab.iaaras.ru/iaaras/gostdown
shmat-razum.blogspot.com/2018/03/gostdown.html
gitlab.iaaras.ru/iaaras/gostdown
shmat-razum.blogspot.com/2018/03/gostdown.html
Sign up to leave a comment.
Документирование программ