yard-api

Usage

See [https://amireh.github.io/yard-api].

Compatibility options

`@argument` tags with names specified before types

For tags that have a type and a name such as the YARD @attr tag, or the yard-api @argument tag, the "correct" syntax is to specify the types before the name. For example:

# @argument [String] name
#   This is compliant with YARD syntax.
#
# @argument name [String]
#   This is not compliant with YARD syntax.

If your project already uses the (incorrect) second syntax and you would like to keep things that way, then you can use the compatibility option leading_argument_name_fix to have yard-api correctify this and understand both flavors.

Configuration

yard-api will look for a file in config/yard_api.yml in the Rails root for customizations. Configuration fields not specified in that file will be filled with the default values found in config/yard_api.yml.

Read that file to view all the available options.

Notes

can only document classes and class methods; modules, root objects, and constants are ignored

Generating the docs for YARD-API

go to the gh-pages branch, check it out if you haven't
run bin/generate-docs
browse index.html

Changelog

6/9/2015 [0.3.5]

In JSON format, an API resource endpoint now contains the name as well.
Changed the topicize() helper in a way that makes the IDs (and URLs of some sections) much more readable

23/8/2015 [0.3.4]

Fixed an issue that prevented overriding the Rake task's options at runtime.
Updated config/yard_api.yml to reflect the recently added options.

17/8/2015 [0.3.3]

Improved the JSON format's output to be more concise and consistent.

30/7/2015 [0.3.1]

Fixed a bug that was listing all the endpoints of a certain controller even if they do not have a route defined. Now, YARD-API will warn about endpoints that have an @API tag but could not be routed.
Greatly improved the performance of generating the Quicklinks table.

29/7/2015 [0.3.0]

major rework of the linking logic, much improvements but some stuff is broken now

28/7/2015 [0.2.3]

dropped the @argument_scope tag
JSON is available as an output format now
added usage documentation, found at [http://amireh.github.io/yard-api]
added an example app
various style improvements
@example_request is now able to output a sample cURL command.

0.1.7

new compatibility option leading_argument_name_fix

15/9/2014

@argument tags can now be formatted in a table by setting the tabular_arguments option to true
@argument_scope: a new tag that improves the formatting of endpoint arguments that are scoped by a common prefix (e.g, nested inside a json object), like user[name] => name
@argument can now parse accepted values in two formats; inline within the types array, or by explicitly writing it in the tag text using any of Accepted values: [...], Accepts: [...], or Possible values: [...]
A new option: strict_arguments that provides a default for the is_required property of @argument tags. This default is used if the tag does not explicitly state Optional or Required in its type specifier.
Support for dynamic javascript and style code based on options. See templates/layout/setup.rb#inline_{javascripts,stylesheets}
A new set of options for customizing layout: content_width, sidebar_width and spacer
github_url and github_branch options for tuning api endpoint source links

14/9/2014

Support for single-page output through the one_file option
Support for resource index generation ("All Resources") through the resource_index option

10/9/2014

Support for github-flavored markdown when you're using Markdown as a markup, and redcarpet as the provider
Syntax highlighting for multiple languages (with auto-detection) using highlight.js
@example_response and @example_request tags now support a title for the response
A new option: copyright for displaying a copyright in the footer of every page
A new option: footer_note for displaying a custom note, like linking to the project's source code, in the footer of every page

License

Released under the AGPLv3 license.

jmarianer/yard-api