https://github.com/instructure/yard-api

A YARD plugin for documenting APIs in Rails projects.
https://github.com/instructure/yard-api

Last synced: 7 days ago
JSON representation

A YARD plugin for documenting APIs in Rails projects.

• Host: GitHub
• URL: https://github.com/instructure/yard-api
• Owner: instructure
• License: agpl-3.0
• Created: 2014-09-10T14:51:43.000Z (about 10 years ago)
• Default Branch: master
• Last Pushed: 2024-03-01T16:51:39.000Z (9 months ago)
• Last Synced: 2024-04-14T20:26:22.984Z (7 months ago)
• Language: CSS
• Homepage: https://amireh.github.io/yard-api/
• Size: 564 KB
• Stars: 7
• Watchers: 3
• Forks: 8
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGES.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# yard-api

[![Build Status](https://travis-ci.org/amireh/yard-api.png)](https://travis-ci.org/amireh/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:

```ruby

# @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](https://github.com/amireh/yard-api/blob/master/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

1. go to the `gh-pages` branch, check it out if you haven't

2. run `bin/generate-docs`

3. browse `index.html`

## Changelog

See CHANGES.md.

## License

Released under the [AGPLv3](http://www.gnu.org/licenses/agpl-3.0.html) license.