¿Cómo proceso un archivo readme con rdoc a la visualización de rubí ayuda escritura de información / uso

Question

Me gustaría mantener mi Documenation uso en un archivo readme (duh) en lugar de los comentarios en la parte superior de mi guión. ¿Cómo llego RDoc :: uso para tirar de la información de uso del readme en lugar de los comentarios del script?

Answer 1

RDoc está diseñado para analizar un archivo de origen, vistazo a los comentarios y sus localizaciones, construir referencias cruzadas de las variables, y, cuando se hace, mantenerlo todo en una salida decente. Debido RDoc está diseñado para trabajar en contra de los archivos de origen que podría no ser la mejor opción para lo que quiere hacer.

En su lugar puede que desee buscar en Yard , que es basado en etiquetas. ¿Puedo obtener mi README.textile en mi RDoc con el formato correcto? tiene alguna información útil para usted también.

En cualquier caso, si no se puede obtener la aplicación para analizar un documento de tipo README como lo desea, podría ser capaz de falsificar por poner todos los documentos en el archivo, junto con la clase y el método en los talones por lo que la analizadores pueden agarrar los parámetros, variables globales, y otros "otras cosas" que necesitan para crear la documentación utilizable.

De lo contrario, es probable que tenga que renunciar a utilizar la ayuda automatizado y escriba todo.

Mi recomendación es hacerlo de la manera RDoc, y el documento dentro de su código. No es difícil de hacer en absoluto, y la salida puede ser muy satisfactorio. Es bastante sorprendente lo bien que un RDoc trabajo puede hacer.

Answer 2

Desde luego, no soy lo suficientemente experimentado para decirle la respuesta, pero por favor me permite un consejo.

La mayoría de los desarrolladores es poco probable que alguna vez actualizar la documentación, incluso si se trata de 3 líneas de código por encima de la aplicación.

Hacer un favor y no hacer que el proceso aún más difícil.

Mantener documentación general separada es una buena idea, sin embargo, pero no tiene nada que ver en su salida generada RDoc-de todos modos.