Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation #34

Merged
merged 3 commits into from
Nov 27, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions .editorconfig
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,3 @@ insert_final_newline = true
indent_size = 2
indent_style = space
trim_trailing_whitespace = true

[*.md]
indent_size = 4
indent_style = tab
3 changes: 3 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Code of Conduct

By contributing to and participating in the development of indieweb-endpoints-ruby, you acknowledge that you have read and agree to the [IndieWeb Code of Conduct](https://indieweb.org/code-of-conduct).
14 changes: 7 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

There are a couple ways you can help improve webmention-client-ruby:

1. Fix an existing [issue][issues] and submit a [pull request][pulls].
1. Review open [pull requests][pulls].
1. Report a new [issue][issues]. _Only do this after you've made sure the behavior or problem you're observing isn't already documented in an open issue._
1. Fix an existing [Issue][issues] and submit a [Pull Request][pulls].
1. Review open [Pull Requests][pulls].
1. Report a new [Issue][issues]. _Only do this after you've made sure the behavior or problem you're observing isn't already documented in an open issue._

## Getting Started

webmention-client-ruby is developed using Ruby 2.7.7 and is additionally tested against Ruby 3.0, 3.1, and 3.2 using [GitHub Actions](https://github.com/indieweb/webmention-client-ruby/actions).
webmention-client-ruby is developed using Ruby 2.7.8 and is tested against additional Ruby versions using [GitHub Actions](https://github.com/indieweb/webmention-client-ruby/actions).

Before making changes to webmention-client-ruby, you'll want to install Ruby 2.7.7. It's recommended that you use a Ruby version managment tool like [rbenv](https://github.com/rbenv/rbenv), [chruby](https://github.com/postmodern/chruby), or [rvm](https://github.com/rvm/rvm). Once you've installed Ruby 2.7.7 using your method of choice, install the project's gems by running:
Before making changes to webmention-client-ruby, you'll want to install Ruby 2.7.8. Using a Ruby version managment tool like [rbenv](https://github.com/rbenv/rbenv), [chruby](https://github.com/postmodern/chruby), or [rvm](https://github.com/rvm/rvm) is recommended. Once you've installed Ruby 2.7.8 using your method of choice, install the project's gems by running:

```sh
bundle install
Expand All @@ -25,11 +25,11 @@ bundle install
1. If your changes would benefit from testing, add the necessary tests and verify everything passes by running `bundle exec rspec`.
1. Commit your changes: `git commit -am 'Add some new feature or fix some issue'`. _(See [this excellent article](https://chris.beams.io/posts/git-commit/) for tips on writing useful Git commit messages.)_
1. Push the branch to your fork: `git push -u origin my-new-feature`.
1. Create a new [pull request][pulls] and we'll review your changes.
1. Create a new [Pull Request][pulls] and we'll review your changes.

## Code Style

Code formatting conventions are defined in the `.editorconfig` file which uses the [EditorConfig](http://editorconfig.org) syntax. There are [plugins for a variety of editors](http://editorconfig.org/#download) that utilize the settings in the `.editorconfig` file. We recommended you install the EditorConfig plugin for your editor of choice.
Code formatting conventions are defined in the `.editorconfig` file which uses the [EditorConfig](http://editorconfig.org) syntax. There are [plugins for a variety of editors](http://editorconfig.org/#download) that utilize the settings in the `.editorconfig` file. We recommended installing the EditorConfig plugin for your editor of choice.

Your bug fix or feature addition won't be rejected if it runs afoul of any (or all) of these guidelines, but following the guidelines will definitely make everyone's lives a little easier.

Expand Down
20 changes: 8 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,24 +15,18 @@

## Getting Started

Before installing and using webmention-client-ruby, you'll want to have [Ruby](https://www.ruby-lang.org) 2.7 (or newer) installed. It's recommended that you use a Ruby version managment tool like [rbenv](https://github.com/rbenv/rbenv), [chruby](https://github.com/postmodern/chruby), or [rvm](https://github.com/rvm/rvm).
Before installing and using webmention-client-ruby, you'll want to have [Ruby](https://www.ruby-lang.org) 2.7 (or newer) installed. Using a Ruby version managment tool like [rbenv](https://github.com/rbenv/rbenv), [chruby](https://github.com/postmodern/chruby), or [rvm](https://github.com/rvm/rvm) is recommended.

webmention-client-ruby is developed using Ruby 2.7.7 and is additionally tested against Ruby 3.0, 3.1, and 3.2 using [GitHub Actions](https://github.com/indieweb/webmention-client-ruby/actions).
webmention-client-ruby is developed using Ruby 2.7.8 and is tested against additional Ruby versions using [GitHub Actions](https://github.com/indieweb/webmention-client-ruby/actions).

## Installation

If you're using [Bundler](https://bundler.io) to manage gem dependencies, add webmention-client-ruby to your project's `Gemfile`:
Add webmention-client-ruby to your project's `Gemfile` and run `bundle install`:

```ruby
gem 'webmention'
```

…and run `bundle install` in your shell.
source "https://rubygems.org"

To install the gem manually, run the following in your shell:

```sh
gem install webmention
gem "webmention-client"
```

## Usage
Expand All @@ -53,7 +47,9 @@ webmention-client-ruby was completely rewritten for version 6 to better support

## Contributing

Interested in helping improve webmention-client-ruby? Awesome! Your help is greatly appreciated. See [CONTRIBUTING.md](https://github.com/indieweb/webmention-client-ruby/blob/main/CONTRIBUTING.md) for details.
See [CONTRIBUTING.md](https://github.com/indieweb/webmention-client-ruby/blob/main/CONTRIBUTING.md) for more on how to contribute to webmention-client-ruby. Your help is greatly appreciated!

By contributing to and participating in the development of webmention-client-ruby, you acknowledge that you have read and agree to the [IndieWeb Code of Conduct](https://indieweb.org/code-of-conduct).

## Acknowledgments

Expand Down
18 changes: 9 additions & 9 deletions USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ Before using webmention-client-ruby, please read the [Getting Started](https://g
With webmention-client-ruby installed, you may send a webmention from a source URL to a target URL:

```ruby
require 'webmention'
require "webmention"

source = 'https://jgarber.example/post/100' # A post on your website
target = 'https://aaronpk.example/post/100' # A post on someone else's website
source = "https://jgarber.example/post/100" # A post on your website
target = "https://aaronpk.example/post/100" # A post on someone else's website

response = Webmention.send_webmention(source, target)
```
Expand Down Expand Up @@ -61,8 +61,8 @@ response.uri #=> HTTP::URI
To send webmentions to multiple target URLs mentioned by a source URL:

```ruby
source = 'https://jgarber.example/post/100'
targets = ['https://aaronpk.example/notes/1', 'https://adactio.example/notes/1']
source = "https://jgarber.example/post/100"
targets = ["https://aaronpk.example/notes/1", "https://adactio.example/notes/1"]

responses = Webmention.send_webmentions(source, targets)
```
Expand All @@ -75,18 +75,18 @@ webmention-client-ruby supports submitting a [vouch](https://indieweb.org/Vouch)

```ruby
# Send a webmention with a vouch URL to a target URL
Webmention.send_webmention(source, target, vouch: 'https://tantek.example/notes/1')
Webmention.send_webmention(source, target, vouch: "https://tantek.example/notes/1")

# Send webmentions with a vouch URL to multiple target URLs
Webmention.send_webmentions(source, targets, vouch: 'https://tantek.example/notes/1')
Webmention.send_webmentions(source, targets, vouch: "https://tantek.example/notes/1")
```

## Discovering mentioned URLs

To retrieve unique URLs mentioned by a URL:

```ruby
urls = Webmention.mentioned_urls('https://jgarber.example/post/100')
urls = Webmention.mentioned_urls("https://jgarber.example/post/100")
```

`Webmention.mentioned_urls` will crawl the provided URL, parse the response body, and return a sorted list of unique URLs. Response bodies are parsed using MIME type-specific rules as noted in the [Verifying a webmention](#verifying-a-webmention) section below.
Expand Down Expand Up @@ -129,7 +129,7 @@ verification = Webmention.verify_webmention(source, target)

# Verify that a source URL links to a target URL and that the vouch URL mentions
# the source URL's domain
verification = Webmention.verify_webmention(source, target, vouch: 'https://tantek.example/notes/1')
verification = Webmention.verify_webmention(source, target, vouch: "https://tantek.example/notes/1")
```

`Webmention.verify_webmention` returns an instance of `Webmention::Verification` which includes the following methods (each returns either `true` or `false`):
Expand Down
Loading