Лучший вики-синтаксис для документации в ruby code и файлах project README

Question

Существует ли какой-либо вики-синтаксис, такой как rdoc, markdown, ...рекомендуется в мире ruby?Иногда я пишу код с открытым исходным кодом и понятия не имею, какой синтаксис мне следует использовать в документах с кодом и в файлах README.Что может быть полезно для меня, что и почему вы этим пользуетесь.

Answer 1

RDoc - это инструмент документирования по умолчанию.Синтаксис RDoc по умолчанию разрешен внутри файлов и библиотек Ruby.

Вы можете обнаружить, что TextTile или Markdown используются вне классов Ruby для текстовых файлов, таких как README или файлы ЖУРНАЛА ИЗМЕНЕНИЙ.Но это не стандартный sintax, поэтому вам понадобится способ сообщить анализатору, с помощью какого синтаксиса записан файл, обычно это расширение файла.

GitHub, например, следует именно этой конвенции.Если не указано расширение .textile или .markdown, файл анализируется как RDoc.

• http://github.com/weppos/whois (.rdoc == Rdoc)
• http://github.com/rails/rails/tree/master/railties/ (без расширения == Rdoc, но не для GitHub)
• http://github.com/technoweenie/restful-authentication/blob/master/README.textile (.текстиль == Текстиль)

Запомни:AFAIK, встроенная документация всегда анализируется как RDoc.

Answer 2

На Github люди в основном используют Rdoc или Textile в качестве формата для своих файлов README.Rdoc также очень полезен для API-документирования вашего кода, поскольку синтаксис действительно хорошо интегрируется в код и его приятно читать.