{@readme ReadmeYard}
readme build.
I plan on implementing safeguards to prevent this kind of thing, but ultimately I want to support editing the README directly. One idea is to leverage git in order to merge README.md changes into the relevant source code and README_YARD.md sections. The README_YARD.md file basically acts as a translation layer between your source code and README, so it can theoretically be used to generate changes both ways. I also think it could be used to keep state, like edit history, for implementing safeguards and awesome features. PRs are welcome; Feel free to reach out 🙂.
Add gem "readme_yard" to your Gemfile and run bundle install or install it yourself with: gem install readme_yard
Run readme build at the command line. This creates a README_YARD.md file if there isn’t one by copying your exisiting README.md file.
README_YARD.md is the template from which readme build generates the README. Readme Yard adds the ability to embed and reference your source code in your README via README_YARD.md.
See Tag Usage.
{@readme ReadmeYard#command_line_usage}
Readme Yard uses YARD tags and custom markdown tags. YARD tags live inside Ruby source code. The markdown tags live inside README_YARD.md.
When the Readme Yard build process encounters a tag in README_YARD.md, it searches the Ruby source code for its YARD tag counterpart, formats the output, and embeds it in the README file.
The next line is a code snippet if you’re looking at README.md and {@readme ReadmeYard.hello_world} if you’re looking at README_YARD.md.
{@readme ReadmeYard.hello_world}
The markdown tag tells Readme Yard to parse the @readme tag located above the hello_world class method located in lib/readme_yard.rb.
To use another "meta" example, {@readme ReadmeYard} is used at the top of this project's README_YARD.md file to generate the first few sentences of this README. ReadmeYard references the class located in lib/readme_yard.rb.
Last one, {@readme ReadmeYard#command_line_usage} is used to generate the "Command Line Usage" section above from the comments of the command_line_usage instance method located in lib/readme_yard.rb. This method is extra meta: it returns the result of formatting its own comments as markdown. In this way, the usage instructions in the comments, the README, and as printed at the command line will always be in sync.
Markdown syntax: {@readme ObjectPath}
YARD syntax: @example <name>
{@readme ReadmeYard::ReadmeTag}
Example usage:
{@example ReadmeYard::CommentTag}
This example "@readme comment" tag embeds the below code snippet via the {@readme ReadmeYard::CommentTag.format_tag_markdown} markdown tag.
{@readme ReadmeYard::CommentTag.format_tag_markdown}
Example usage:
{@example ReadmeYard::SourceTag}
This example "@readme source" tag embeds the below code snippet via the {@readme ReadmeYard::SourceTag.format_tag_markdown} markdown tag.
{@readme ReadmeYard::SourceTag.format_tag_markdown}
Example usage:
{@example ReadmeYard::ObjectTag}
This example "@readme object" tag embeds the below code snippet via the {@readme ReadmeYard::ObjectTag.format_tag_markdown} markdown tag.
{@readme ReadmeYard::ObjectTag.format_tag_markdown}
Markdown syntax: {@example ObjectPath}
YARD syntax: @example
{@readme ReadmeYard.hello_world}
The below example code is generated from {@example ReadmeYard.hello_world} because, as you can see above, the "hello_world" class method has an @example tag.
{@example ReadmeYard.hello_world}
Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.
If you're interested in contributing, but don't know where to get started, feel free to message me on twitter at @mattruzicka. I have a lot of ideas!
Thanks for taking the time to think about me, the README.
🌿 🥏 🌱 ⚽