robodoc

Про Robodoc я писала в 2013 году в блог https://ladycat.wordpress.com/2013/04/15/robodoc/. Этот текст развитие тогдашнего, перенос того, что было в моей «энциклопедии всего» году так к 2019.

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

И поняла я, что надо как-то озадачиваться документацией. М-да. Идея завести файлик, куда писать названия-описания, уже как-то несимпатична. Идея, что надо будет помнить про этот файлик и его —- о ужас! —- обновлять, буде мне взбредёт в голову что-то где-то маленько подправить. Бррр! :)

Ладно, подумала я, а что мне тогда нужно-то? А нужно мне, чтобы какая-нибудь прога сама собирала данные. Из файликов. Файлики я, уж так и быть, заточить под это возьмусь. Не все, не сразу, но возьмусь. Да, значит, чтоб прога собирала данные, создавала мне большой html-файл с оглавлением, в котором я бы могла обозреть, что у меня есть, и легко уточнить, что такое вот это, которое я забыла. Это ещё и красиво было бы.

Нашла robodoc. Если бы у меня были только перловые скриптики, скорее всего, я разбиралась бы, как добиться желаемого от POD. Но у меня ещё bash, tcl и python. Кое-что моё, больше цельнотянутого, разумеется :)

Всё, что хотелось бы увидеть в создаваемой документации, пишется в комментариях. За подробностями лучше обратиться к документации robodoc-а. Она англоязычная, но простая и небольшая по объёму.

Да, кстати, если вам скажут, что robodoc не умеет обращаться с каким-то языком программирования, уточните, что вам хотели сказать. Robodoc не особо вникает в синтаксис языка, и скажем, строки документации он вынимать не будет. Просто укажите ему, как в языке делаются строчные и, если есть, блочные комментарии, напишите в комментариях всё нужное, и robodoc честно выполнит свою часть работы. :)

Не так давно очередной раз озадачилась темой, посмотрела инструменты и всё такое. Потому что традиционно хочется порядка на компе и потому что robodoc что-то исчез из репозитария дебиана. Уточним сразу, я по-прежнему только чуток балуюсь скриптиками, на большое не замахивалась. Только на большие тексты, и то почти втайне )

Все инструменты делятся, как я поняла, на две группы.

• Можно выполнять/компилировать или что там бишь сразу тот файл, который с кодом и документацией. Документация убрана в комментарии, оттуда её можно извлечь.
  • http://rfsber.home.xs4all.nl/Robo/ или https://github.com/gumpu/ROBODoc больше про шапки файлов,
  • http://www.naturaldocs.org/%7D%7BNaturalDocs больше про документирование содержимого,
  • есть ещё несколько сравнительно универсальных генераторов документации и уйма тех, которые предназначены для конкретных языков. https://ru.wikipedia.org/wiki/Генератор_документации. Специализированные часто не ограничиваются тем, что пишет человек, но и пытаются что-то анализировать сами.
• Что-то делать вот так запросто нельзя, сначала надо обработать файл чем-то для извлечения отдельно документации, отдельно исходного кода. Зато можно писать, как удобно человеку, в любой последовательности. literate programming.
  • org-babel для емаксеров,
  • http://www.cs.tufts.edu/~nr/noweb/ для всех,
  • и ещё всякого см. по ссылкам со всё той же странички literate programming.

Оба подхода имеют свои хорошие стороны.

Для папочки со скриптиками я с удовольствием использовала robodoc. Там надо просто написать в шапке файла, что это и для чего, и получается набор страничек, где есть оглавление со всеми скриптиками и выделенные странички по каждому. Жаль, сейчас не знаю ничего более актуального такого, чтоб просто ставилось. :)

Для того, что пытаюсь писать сама - в оргмодном файле пишу, чего я хочу, потихоньку превращаю это в строчки кода с обширными пояснениями, что они делают, куда идут, почему именно так и т.п., при экспорте-танглении они собираются в нужной последовательности - благо orgmode умеет noweb-style references. Там же заодно можно и рободочную шапку сделать (или комментарии для naturaldocs или чего ещё, но это я не). Не надо выбирать одно, можно пользоваться обоими способами разом. Зато вообще не представляю, как люди ещё и совсем отдельно документацию пишут и поддерживают! Какая самодисциплина!

И ещё несколько лет назад, точно не помню, но до 2009 года, я поняла, что мне не подходят для написания текстов всякие msword-ы и oowriter-ы просто потому, что в тексте должно быть больше, чем только текст, который ``что видите, то и получите''. Мне нужны комментарии, как минимум. Нужна возможность держать в том же файле всё, что очень плотно связано с текстом, но что я не хочу показывать читателю.

Org-mode подошёл, там есть возможность довольно гибко управлять экспортированием и довольно много способов держать своё около экспортируемого - будь то целые закомментированные разделы, строчные комментарии, которые можно вставить хоть в середину абзаца, или сворачивающиеся «ящики»-drawers.

#***** My_utilities/something
# NAME

#     Item name plus a short description.
# COPYRIGHT

#     Who own the copyright : "(c) <year>-<year> by <company/person>"
# SYNOPSIS , USAGE

#     How to use it.
# FUNCTION , DESCRIPTION , PURPOSE

#     What does it do.
# AUTHOR

#     Who wrote it.
# CREATION DATE

#     When did the work start.
# MODIFICATION HISTORY , HISTORY

#     Who has done which changes and when.
# INPUTS , ARGUMENTS , OPTIONS , PARAMETERS , SWITCHES

#     What can we feed into it.
# OUTPUT , SIDE EFFECTS

#     What output is made.
# RESULT , RETURN VALUE

#     What do we get returned.
# EXAMPLE

#     A clear example of the items use.
# NOTES

#     Any annotations
# DIAGNOSTICS

#     Diagnostic output.
# WARNINGS , ERRORS

#     Warning and error-messages.
# BUGS

#     Known bugs.
# TODO , IDEAS

#     What to implement next and ideas.
# PORTABILITY

#     Where does it come from, where will it work.
# SEE ALSO

#     References to other functions, man pages, other documentation.
# METHODS , NEW METHODS

#     OOP methods.
# ATTRIBUTES , NEW ATTRIBUTES

#     OOP attributes.
# TAGS

#     Tag-item description.
# DERIVED FROM

#     OOP super class.
# DERIVED BY

#     OOP sub class.
# USES , CHILDREN

#     What modules are used by this one.
# USED BY , PARENTS

#     Which modules do use this one.
# COMMANDS

#     Command description.
# SOURCE

#     Source code inclusion.