<commit_before># DocMyRoutes

[![Build Status](https://travis-ci.org/Workday/doc_my_routes.svg)](https://travis-ci.org/Workday/doc_my_routes)
[![Gem Version](https://badge.fury.io/rb/doc_my_routes.svg)](https://badge.fury.io/rb/doc_my_routes)

This gem provides helpers to annotate Sinatra routes and automatically generate HTML API documentation.

Routes can be annotated with information such as:
* summary (short description)
* notes (extended description)
* content type produced
* returning status codes

In addition, examples can be linked to routes and automatically associated.
See the section "Associating examples" for more information.

## Installation

DocMyRoutes can be installed via Rubygems or compiling and installing it yourself as:

```
$ gem build doc_my_routes.gemspec
$ gem install doc_my_routes-VERSION.gem
```

## Usage

Using DocMyRoutes is quite straight-forward and it basically requires two steps:
* configure DocMyRoutes and annotate your application
* triggering the generation of the documentation

### Configuring DocMyRoutes and annotating routes

First of all, DocMyRoutes needs to be configured with your project title
and description (see the *Customisation* section for other options).

Simply ```require 'doc_my_routes'``` and set the two options:

```ruby
DocMyRoutes.configure do |config|
  config.title = "My Application"
  config.description = "My Application description"
end
```

then ```extend DocMyRoutes::Annotatable```
in your Sinatra application and start annotating your routes.

Example:
```ruby
require 'sinatra/base'
require 'doc_my_routes'

DocMyRoutes.configure do |config|
  config.title = "My Application"
  config.description = "My Application description"
end

class MyApp < Sinatra::Base
  # Add support for documenting routes
  extend DocMyRoutes::Annotatable

  summary 'Example route'
  notes 'Simple route that gets an ID and returns a string'
  produces 'text/plain'
  status_codes [200]
  get '/:id' do |id|
    "Received #{id}"
  end
end
```

### Generating documentation

In your *config.ru* (or in your main .rb file) you can trigger the generation
of the documentation invoking ```DocMyRoutes::Documentation.generate```.

Example:
```ruby
require_relative 'my_app'

# Configure your app here...

...
# If documentation requested (e.g., using an input flag)
DocMyRoutes::Documentation.generate
...
```

This will generate HTML API documentation to the configured ```destination_dir```. By default the destination directory is ```doc/api```.

### Associating examples

In addition to the helpers described above, DocMyRoutes provides a
```examples_regex``` helper that will automatically link call examples to the
documentation of that route.

An example represents a request/response interaction related to that route and
it's application specific. DocMyRoutes provides a structure to automatically<commit_msg>Document :partial_html<commit_after># DocMyRoutes

[![Build Status](https://travis-ci.org/Workday/doc_my_routes.svg)](https://travis-ci.org/Workday/doc_my_routes)
[![Gem Version](https://badge.fury.io/rb/doc_my_routes.svg)](https://badge.fury.io/rb/doc_my_routes)

This gem provides helpers to annotate Sinatra routes and automatically generate HTML API documentation.

Routes can be annotated with information such as:
* summary (short description)
* notes (extended description)
* content type produced
* returning status codes

In addition, examples can be linked to routes and automatically associated.
See the section "Associating examples" for more information.

## Installation

DocMyRoutes can be installed via Rubygems or compiling and installing it yourself as:

```
$ gem build doc_my_routes.gemspec
$ gem install doc_my_routes-VERSION.gem
```

## Usage

Using DocMyRoutes is quite straight-forward and it basically requires two steps:
* configure DocMyRoutes and annotate your application
* triggering the generation of the documentation

### Configuring DocMyRoutes and annotating routes

First of all, DocMyRoutes needs to be configured with your project title
and description (see the *Customisation* section for other options).

Simply ```require 'doc_my_routes'``` and set the two options:

```ruby
DocMyRoutes.configure do |config|
  config.title = "My Application"
  config.description = "My Application description"
end
```

then ```extend DocMyRoutes::Annotatable```
in your Sinatra application and start annotating your routes.

Example:
```ruby
require 'sinatra/base'
require 'doc_my_routes'

DocMyRoutes.configure do |config|
  config.title = "My Application"
  config.description = "My Application description"
end

class MyApp < Sinatra::Base
  # Add support for documenting routes
  extend DocMyRoutes::Annotatable

  summary 'Example route'
  notes 'Simple route that gets an ID and returns a string'
  produces 'text/plain'
  status_codes [200]
  get '/:id' do |id|
    "Received #{id}"
  end
end
```

Note that configuring ```format = :partial_html``` generates an HTML snippet
that can be easily embedded, instead of a complete HTML page.

### Generating documentation

In your *config.ru* (or in your main .rb file) you can trigger the generation
of the documentation invoking ```DocMyRoutes::Documentation.generate```.

Example:
```ruby
require_relative 'my_app'

# Configure your app here...

...
# If documentation requested (e.g., using an input flag)
DocMyRoutes::Documentation.generate
...
```

This will generate HTML API documentation to the configured ```destination_dir```. By default the destination directory is ```doc/api```.

### Associating examples

In addition to the helpers described above, DocMyRoutes provides a
```examples_regex``` helper that will automatically link call examples to the
documentation of that route.

An example represents a request/response interaction related to that route and
it's application specific. DocMyRoutes provides a structure to automatically
{'fraction_non_alphanumeric': 0.08853902149991535, 'fraction_numerical': 0.001015744032503809, 'mean_word_length': 5.212407991587802, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '33284', 'n_tokens_mistral': 1667, 'n_tokens_neox': 1625, 'n_words': 650}