Comment traiter un fichier readme avec rdoc pour afficher l'aide / informations d'utilisation de script Ruby

Question

Je voudrais garder mon Documenation d'utilisation dans un fichier Readme (duh) au lieu des commentaires au début de mon script. Comment puis-je obtenir RDoc :: utilisation pour tirer les informations d'utilisation de la readme au lieu des commentaires de script?

Answer 1

RDoc est conçu pour analyser un fichier source, regardez les commentaires et leur emplacement, construire des références croisées des variables, et, lorsque vous avez terminé, tout lier en une sortie décente. Parce que RDoc est conçu pour fonctionner sur les fichiers sources, il pourrait ne pas être le meilleur choix pour ce que vous voulez faire.

Au lieu de cela, vous voudrez peut-être regarder dans cour , qui est basée sur des balises. Puis-je obtenir mes README.textile dans mon RDoc avec le bon formatage? a des informations utiles pour vous aussi.

Dans les deux cas, si vous ne pouvez pas obtenir l'application pour analyser un document de type README comme vous voulez, vous pourriez être en mesure d'usurper en mettant tous vos documents dans le fichier, ainsi que des talons de classe et de méthode de sorte que la parseurs peuvent saisir les paramètres, globals et autres « joyeusetés » dont ils ont besoin pour créer une documentation utilisable.

Dans le cas contraire, vous devrez probablement renoncer à l'aide de l'aide automatique et tapez tout dans.

Ma recommandation est de le faire de la façon RDoc et document à l'intérieur de votre code. Il est difficile de ne pas faire du tout, et la sortie peut être très satisfaisante. Il est assez incroyable de voir comment une bonne RDoc de travail peut faire.

Answer 2

Je ne suis certainement pas assez d'expérience pour vous dire la réponse, mais s'il vous plaît me permettre un conseil.

La plupart des développeurs ne sont pas susceptibles de mettre à jour jamais la documentation même si elle est 3 lignes de code ci-dessus la mise en œuvre.

Faites une faveur et ne font pas le processus encore plus difficile.

Tenue d'une documentation générale distincte est une bonne idée mais, mais il n'a rien à voir dans la sortie générée RDoc-même.