wordpress_client 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: db9e904a3d97870c4ca1077dd350b7466ed63716
-  data.tar.gz: a40076833498ef6f90faa6a592da1cb4898d6972
+  metadata.gz: 07d49e4293481ae704072d12288a60a97d1182ec
+  data.tar.gz: be101dbc5a42658d3b9639bf0cc6d1753f246d00
 SHA512:
-  metadata.gz: 539fb8ba5bceeb76a86b32336792a79ffd7df4c8a2a0abb1a2632fdf64aac1d0a4fe8720c3036697f0248746e00e9f30742b9efcc30c43e61ee8b8bed29341ff
-  data.tar.gz: c456230269ebcac532ca2d4b7e141134822243240f620b4d3cb06f5067a29a3c05b16246ad5cd38cbe19ca1484863e57c4bd20e46b534da27adb49143a279ac6
+  metadata.gz: 8cec642f556f04ff4f5c418dda5c560956b7a1c1d3cd17184a2312a0a9d35daf5c9fb60834055375d3b27b0c1623d74b3b9bf860adb9334bc476d2c22b13f87a
+  data.tar.gz: d149bb98f48f1f164aef95cbad14d60669b553abd78f2968ccae16be2e0582d887d2af3b1e81f8dda8fa29e69958530a95dfe37168020ac04b40a3a8ba73f709

data/.codeclimate.yml

@@ -0,0 +1,14 @@
+---
+engines:
+  rubocop:
+    enabled: true
+  bundler-audit:
+    enabled: true
+  fixme:
+    enabled: true
+ratings:
+  paths:
+  - lib/**/*.rb
+exclude_paths:
+- spec/**/*
+- ".*"

data/.yardopts

@@ -0,0 +1 @@
+--no-private --embed-mixins

data/Changelog.md

@@ -0,0 +1,3 @@
+# 1.0.0
+
+* Initial release

data/README.md

@@ -1,14 +1,14 @@
 # WordpressClient
 
-WordpressClient is a very simple client to the Wordpress API, version 2 beta 8.0.
+WordpressClient is a very simple client for the Wordpress [WP REST API plugin][api] (version 2 beta 8.0).
 
-**NOTE:** The repository is still named `wpclient` as we're in the middle of a rename. Some references might persist until it's completed.
-
-[![Circle CI](https://circleci.com/gh/hemnet/wpclient.svg?style=svg)](https://circleci.com/gh/hemnet/wpclient) [![Code Climate](https://codeclimate.com/repos/5645938269568041da00cded/badges/5e870b57428f23c1f2ff/gpa.svg)](https://codeclimate.com/repos/5645938269568041da00cded/feed) [![Test Coverage](https://codeclimate.com/repos/5645938269568041da00cded/badges/5e870b57428f23c1f2ff/coverage.svg)](https://codeclimate.com/repos/5645938269568041da00cded/coverage)
+[![Circle CI](https://circleci.com/gh/hemnet/wordpress_client.svg?style=svg)](https://circleci.com/gh/hemnet/wordpress_client) [![Code Climate](https://codeclimate.com/repos/5645938269568041da00cded/badges/5e870b57428f23c1f2ff/gpa.svg)](https://codeclimate.com/repos/5645938269568041da00cded/feed) [![Test Coverage](https://codeclimate.com/repos/5645938269568041da00cded/badges/5e870b57428f23c1f2ff/coverage.svg)](https://codeclimate.com/repos/5645938269568041da00cded/coverage) [![Gem Version](https://badge.fury.io/rb/wordpress_client.svg)](https://badge.fury.io/rb/wordpress_client)
 
 ## Usage
 
-Initialize a client with a username, password and API URL. You can then search for posts.
+**[Read the full API documentation][docs]**
+
+Initialize a client with a user name, password and API URL. You can then search for posts.
 
 ```ruby
 client = WordpressClient.new(url: "https://example.com/wp-json/", username: "example", password: "example")
@@ -36,7 +36,7 @@ updated_post.title_html # => "Updated"
 
 You need to install Docker and set it up for your machine. Note that you need `docker-machine` to run Docker on OS X.
 
-Run tests using the normal `rspec` command after installing all bundles. The first time the integration tests are run, a docker image will be built that hosts a Wordpress installation, but the image will be re-used on subsequent runs.
+Run tests using the normal `rspec` command after installing all bundles.
 
 ```
 bundle exec rspec
@@ -52,6 +52,12 @@ end
 
 The normal `rspec` command will *not* use this filter in case it is ever committed accidentally, so CI can catch any problems.
 
+## Releasing a new version
+
+The normal gem release cycle works using `rake release`.
+
+If you make changes to the docker image, you can release it using `rake docker:release`.
+
 ## Copyright & License
 
 Copyright © 2015 Hemnet Service HNS AB
@@ -61,3 +67,6 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+[api]: http://v2.wp-api.org/
+[docs]: http://www.rubydoc.info/gems/wordpress_client/

data/Rakefile

@@ -1 +1,36 @@
 require "bundler/gem_tasks"
+require "yard"
+require "wordpress_client/version"
+
+YARD::Rake::YardocTask.new
+
+namespace :docker do
+  DOCKER_DIR = File.expand_path("../spec/docker", __FILE__).freeze
+  IMAGE_NAME = "hemnet/wordpress_client_test".freeze
+  DEV_IMAGE = [IMAGE_NAME, "dev"].join(":").freeze
+
+  desc "Build the docker image"
+  task :build do
+    sh "docker", "build", "-t", DEV_IMAGE, DOCKER_DIR
+  end
+
+  desc "Release current dev build"
+  task release: :build do
+    version = prompt "Which version do you want to release"
+    raise "Invalid version string" unless version =~ /\A[\d.]+\z/
+
+    latest = prompt "Do you want this to be the :latest release? [Y/n]"
+    latest = (latest.empty? || latest.downcase == "y")
+
+    sh "docker", "tag", DEV_IMAGE, "#{IMAGE_NAME}:#{version}"
+    sh "docker", "tag", "-f", DEV_IMAGE, "#{IMAGE_NAME}:latest" if latest
+
+    sh "docker", "push", "#{IMAGE_NAME}:#{version}"
+    sh "docker", "push", "#{IMAGE_NAME}:latest" if latest
+  end
+end
+
+def prompt(message)
+  print "#{message} > "
+  STDIN.gets.strip
+end

data/lib/wordpress_client.rb

@@ -19,7 +19,26 @@ require "wordpress_client/replace_terms"
 require "wordpress_client/replace_metadata"
 
 module WordpressClient
-  def self.new(*args)
-    Client.new(Connection.new(*args))
+  # Initialize a new client using the provided connection details.
+  # You need to provide authentication details, and the user must have +edit+
+  # permissions on the blog if you want to read Post Meta, or to modify
+  # anything.
+  #
+  # @example
+  #   client = WordpressClient.new(
+  #     url: "https://blog.example.com/wp-json",
+  #     username: "bot",
+  #     password: ENV.fetch("WORDPRESS_PASSWORD"),
+  #   )
+  #
+  # @see Client Client, for the methods available after creating the connection.
+  #
+  # @param url [String] The base URL to the wordpress install, including
+  #                     +/wp-json+.
+  # @param username [String] A valid username on the wordpress installation.
+  # @param password [String] The password for the provided user.
+  # @return {Client}
+  def self.new(url:, username:, password:)
+    Client.new(Connection.new(url: url, username: username, password: password))
   end
 end

data/lib/wordpress_client/category.rb

@@ -1,4 +1,6 @@
 module WordpressClient
+  # Represents a category from Wordpress.
+  # @see Term
   class Category < Term
   end
 end

data/lib/wordpress_client/client.rb

@@ -4,6 +4,19 @@ module WordpressClient
       @connection = connection
     end
 
+    # @!group Posts
+
+    # Find {Post Posts} matching given parameters.
+    #
+    # @example Finding 5 posts in the Important category
+    #   posts = client.posts(per_page: 5, category_slug: "important")
+    #
+    # @param page [Fixnum] Current page for pagination. Defaults to 1.
+    # @param per_page [Fixnum] Posts per page. Defaults to 10.
+    # @param category_slug [String, nil] Find posts belonging to a category with the given slug.
+    # @param tag_slug [String, nil] Find posts belonging to a tag with the given slug.
+    #
+    # @return {PaginatedCollection[Post]} Paginated collection of the found posts.
     def posts(per_page: 10, page: 1, category_slug: nil, tag_slug: nil)
       filter = {}
       filter[:category_name] = category_slug if category_slug
@@ -13,23 +26,21 @@ module WordpressClient
       )
     end
 
-    def categories(per_page: 10, page: 1)
-      connection.get_multiple(Category, "terms/category", page: page, per_page: per_page)
-    end
-
-    def tags(per_page: 10, page: 1)
-      connection.get_multiple(Tag, "terms/tag", page: page, per_page: per_page)
-    end
-
-    def media(per_page: 10, page: 1)
-      connection.get_multiple(Media, "media", page: page, per_page: per_page)
-    end
-
+    # Find the {Post} with the given ID, or raises an error if not found.
+    #
+    # @return {Post}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
     def find_post(id)
       connection.get(Post, "posts/#{id.to_i}", _embed: nil, context: "edit")
     end
 
-    def find_by_slug(slug)
+    # Find the first {Post} with the given slug, or raises an error if it cannot be found.
+    #
+    # @return {Post}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def find_post_by_slug(slug)
       posts = connection.get_multiple(
         Post, "posts", per_page: 1, page: 1, filter: {name: slug}, _embed: nil
       )
@@ -40,18 +51,27 @@ module WordpressClient
       end
     end
 
-    def find_category(id)
-      connection.get(Category, "terms/category/#{id.to_i}")
-    end
-
-    def find_tag(id)
-      connection.get(Tag, "terms/tag/#{id.to_i}")
-    end
-
-    def find_media(id)
-      connection.get(Media, "media/#{id.to_i}")
-    end
-
+    # Create a new {Post} with the given attributes in Wordpress and return it.
+    #
+    # In addition to {http://v2.wp-api.org/reference/posts/ the accepted
+    # parameters of the API}, this method also takes the following keys:
+    # * +:meta+
+    # * +:category_ids+
+    # * +:tag_ids+
+    #
+    # @see http://v2.wp-api.org/reference/posts/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   accepted parameters or the custom parameters listed
+    #                   above.
+    # @option attributes [Hash<String,String>] meta Hash of meta values.
+    # @option attributes [Array<Fixnum>] category_ids List of category IDs the
+    #                                    Post should belong to.
+    # @option attributes [Array<Fixnum>] tag_ids List of tag IDs the Post
+    #                                    should have.
+    #
+    # @return {Post}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
     def create_post(attributes)
       post = connection.create(Post, "posts", attributes, redirect_params: {_embed: nil})
 
@@ -67,14 +87,34 @@ module WordpressClient
       end
     end
 
-    def create_category(attributes)
-      connection.create(Category, "terms/category", attributes)
-    end
-
-    def create_tag(attributes)
-      connection.create(Tag, "terms/tag", attributes)
-    end
-
+    # Update the {Post} with the given id, setting the supplied attributes in
+    # Wordpress and returning an updated Post.
+    #
+    # In addition to {http://v2.wp-api.org/reference/posts/ the accepted
+    # parameters of the API}, this method also takes the following keys:
+    # * +:meta+
+    # * +:category_ids+
+    # * +:tag_ids+
+    #
+    # @example Changing the title of a Post
+    #   new_post = client.update_post(post.id, title: "A better title")
+    #   new_post.title_html #=> "A better title"
+    #
+    # @see http://v2.wp-api.org/reference/posts/ List of accepted parameters
+    # @param id [Fixnum] ID of the post to update.
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   accepted parameters or the custom parameters listed
+    #                   above.
+    # @option attributes [Hash<String,String>] meta Hash of meta values.
+    # @option attributes [Array<Fixnum>] category_ids List of category IDs the
+    #                                    Post should belong to.
+    # @option attributes [Array<Fixnum>] tag_ids List of tag IDs the Post
+    #                                    should have.
+    #
+    # @return {Post}
+    # @raise {NotFoundError}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
     def update_post(id, attributes)
       post = connection.patch(Post, "posts/#{id.to_i}?_embed", attributes)
 
@@ -90,22 +130,180 @@ module WordpressClient
       end
     end
 
+    # Deletes the {Post} with the given ID.
+    #
+    # @param id [Fixnum] The {Post} ID.
+    # @param force [Boolean] When +false+, the Post will be put in the "Trash"
+    #        of Wordpress. +true+ causes the Post to be irrevocably deleted.
+    #
+    # @return true always
+    def delete_post(id, force: false)
+      connection.delete("posts/#{id.to_i}", {"force" => force})
+    end
+
+    # @!group Categories
+
+    # Find {Category Categories} in the Wordpress install.
+    #
+    # @return {PaginatedCollection[Category]}
+    def categories(per_page: 10, page: 1)
+      connection.get_multiple(Category, "terms/category", page: page, per_page: per_page)
+    end
+
+    # Find {Category} with the given ID.
+    #
+    # @return {Category}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def find_category(id)
+      connection.get(Category, "terms/category/#{id.to_i}")
+    end
+
+    # Create a new {Category} with the given attributes.
+    #
+    # @see http://v2.wp-api.org/reference/taxonomies/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    # @option attributes [String] name Name of the category (required).
+    # @option attributes [String] slug Slug of the category (optional).
+    # @option attributes [String] description Description of the category (optional).
+    #
+    # @return {Category} the new Category
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def create_category(attributes)
+      connection.create(Category, "terms/category", attributes)
+    end
+
+    # Update the {Category} with the given id, setting the supplied attributes.
+    #
+    # @see http://v2.wp-api.org/reference/taxonomies/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    # @option attributes [String] name Name of the category.
+    # @option attributes [String] slug Slug of the category.
+    # @option attributes [String] description Description of the category.
+    #
+    # @return {Category} the updated Category
+    # @raise {NotFoundError}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
     def update_category(id, attributes)
       connection.patch(Category, "terms/category/#{id.to_i}", attributes)
     end
 
+    # @!group Tags
+
+    # Find {Tag Tags} in the Wordpress install.
+    #
+    # @return {PaginatedCollection[Tag]}
+    def tags(per_page: 10, page: 1)
+      connection.get_multiple(Tag, "terms/tag", page: page, per_page: per_page)
+    end
+
+    # Find {Tag} with the given ID.
+    #
+    # @return {Tag}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def find_tag(id)
+      connection.get(Tag, "terms/tag/#{id.to_i}")
+    end
+
+    # Create a new {Tag} with the given attributes.
+    #
+    # @see http://v2.wp-api.org/reference/taxonomies/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    # @option attributes [String] name Name of the tag (required).
+    # @option attributes [String] slug Slug of the tag (optional).
+    # @option attributes [String] description Description of the tag (optional).
+    #
+    # @return {Tag} the new Tag
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def create_tag(attributes)
+      connection.create(Tag, "terms/tag", attributes)
+    end
+
+    # Update the {Tag} with the given id, setting the supplied attributes.
+    #
+    # @see http://v2.wp-api.org/reference/taxonomies/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    # @option attributes [String] name Name of the tag.
+    # @option attributes [String] slug Slug of the tag.
+    # @option attributes [String] description Description of the tag.
+    #
+    # @return {Tag} the updated Tag
+    # @raise {NotFoundError}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
     def update_tag(id, attributes)
       connection.patch(Tag, "terms/tag/#{id.to_i}", attributes)
     end
 
-    def update_media(id, attributes)
-      connection.patch(Media, "media/#{id.to_i}", attributes)
+    # @!group Media
+
+    # Find {Media} in the Wordpress install.
+    #
+    # @return {PaginatedCollection[Media]}
+    def media(per_page: 10, page: 1)
+      connection.get_multiple(Media, "media", page: page, per_page: per_page)
     end
 
+    # Find {Media} with the given ID.
+    #
+    # @return {Media}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def find_media(id)
+      connection.get(Media, "media/#{id.to_i}")
+    end
+
+    # Create a new {Media} by uploading a IO stream.
+    #
+    # You need to provide both MIME type and filename for Wordpress to accept
+    # the file.
+    #
+    # @example Uploading a JPEG from a request
+    #   media = client.upload(
+    #     request.body_stream, filename: "foo.jpg", mime_type: "image/jpeg"
+    #   )
+    #
+    # @param io [IO-like object] IO stream (for example an open file) that will
+    #        be the body of the media.
+    # @param mime_type [String] the MIME type of the IO stream
+    # @param filename [String] the filename that Wordpress should see. Requires
+    #        a file extension to make Wordpress happy.
+    #
+    # @return {Media} the new Media
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    # @see #upload_file #upload_file - a shortcut for uploading files on disk
     def upload(io, mime_type:, filename:)
       connection.upload(Media, "media", io, mime_type: mime_type, filename: filename)
     end
 
+    # Create a new {Media} by uploading a file from disk.
+    #
+    # You need to provide MIME type for Wordpress to accept the file. The
+    # filename that Wordpress sees will automatically be derived from the
+    # passed path.
+    #
+    # @example Uploading a JPEG from disk
+    #   media = client.upload_file(
+    #     "assets/ocean.jpg", mime_type: "image/jpeg"
+    #   )
+    #
+    # @param filename [String] a path to a readable file.
+    # @param mime_type [String] the MIME type of the file.
+    #
+    # @return {Media} the new Media
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    # @see #upload #upload - for when you want to upload something that isn't a
+    #              file on disk, or need extra flexibility
     def upload_file(filename, mime_type:)
       path = filename.to_s
       File.open(path, 'r') do |file|
@@ -113,10 +311,22 @@ module WordpressClient
       end
     end
 
-    def delete_post(id, force: false)
-      connection.delete("posts/#{id.to_i}", {"force" => force})
+    # Update the {Media} with the given id, setting the supplied attributes.
+    #
+    # @see http://v2.wp-api.org/reference/media/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    #
+    # @return {Media} The updated Media
+    # @raise {NotFoundError}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def update_media(id, attributes)
+      connection.patch(Media, "media/#{id.to_i}", attributes)
     end
 
+    # @!endgroup
+
     def inspect
       "#<WordpressClient::Client #{connection.inspect}>"
     end

data/lib/wordpress_client/connection.rb

@@ -2,6 +2,7 @@ require "faraday"
 require "json"
 
 module WordpressClient
+  # @private
   class Connection
     attr_reader :url, :username
 

data/lib/wordpress_client/errors.rb

@@ -1,10 +1,45 @@
 module WordpressClient
-  Error = Class.new(::StandardError)
+  # Base class for all errors emitted from this gem. Rescue this in order to
+  # catch everything.
+  #
+  # See the list of subclasses for more specific error types.
+  class Error < ::StandardError; end
 
-  UnauthorizedError = Class.new(Error)
+  # Raised when the clients attempt to do something that the user isn't
+  # authorized to do.
+  #
+  # This could happen if you try to delete a post and the user only has
+  # read-only access, for example.
+  # It would also happen if you provide bad authentication details.
+  #
+  # @see Error
+  class UnauthorizedError < Error; end
 
-  TimeoutError = Class.new(Error)
-  ServerError = Class.new(Error)
-  NotFoundError = Class.new(Error)
-  ValidationError = Class.new(Error)
+  # Raised when a request times out.
+  #
+  # @see Error
+  class TimeoutError < Error; end
+
+  # Raised when the server had an error, or when the server returned something
+  # unexpected, despite saying everything went okay. It's the most generic
+  # "Something went wrong with the request" error.
+  #
+  # @see Error
+  class ServerError < Error; end
+
+  # Raised when trying to find a resource that doesn't exist. It will also
+  # happen when you try to update a resource that doesn't exist.
+  #
+  # Lack of authorization can also mask actual resources so it appears that
+  # they don't exist.
+  #
+  # @see Error
+  class NotFoundError < Error; end
+
+  # Raised when the server rejects the body of a request. The error message
+  # will often include information about why the body was rejected, but it is
+  # not guaranteed.
+  #
+  # @see Error
+  class ValidationError < Error; end
 end

data/lib/wordpress_client/media.rb

@@ -1,4 +1,5 @@
 module WordpressClient
+  # Represents a media record in Wordpress.
   class Media
     attr_accessor(
       :id, :slug, :title_html, :description,
@@ -6,10 +7,41 @@ module WordpressClient
       :guid, :link, :media_details
     )
 
+    # @!attribute [rw] title_html
+    #   @return [String] the title of the media, HTML escaped
+    #   @example
+    #     media.title_html #=> "Sunset — Painting by some person"
+
+    # @!attribute [rw] date
+    #   @return [Time, nil] the date of the media, in UTC if available
+
+    # @!attribute [rw] updated_at
+    #   @return [Time, nil] the modification date of the media, in UTC if available
+
+    # @!attribute [rw] guid
+    #   Returns the permalink/GUID – or +source_url+ – of the media.
+    #
+    #   Media that are embedded in posts have a +source_url+ attribute and no
+    #   +guid+, and stand-alone media has a +guid+ but no +source_url+. They
+    #   are both backed by the same data, so this method handles both cases,
+    #   and is aliased to both names.
+    #
+    #   @return [String] the permalink/GUID – or +source_url+ – of the media
+
+    # @!attribute [rw] media_details
+    #   Returns the media details if available.
+    #
+    #   Media details cannot be documented here. It's up to you to handle this
+    #   generic "payload" attribute the best way you can.
+    #
+    #   @return [Hash<String,Object>] the media details returned from the server
+
+    # @api private
     def self.parse(data)
       MediaParser.parse(data)
     end
 
+    # Creates a new instance, populating the fields with the passed values.
     def initialize(
       id: nil,
       slug: nil,

data/lib/wordpress_client/media_parser.rb

@@ -1,4 +1,5 @@
 module WordpressClient
+  # @private
   class MediaParser
     include RestParser
 

data/lib/wordpress_client/paginated_collection.rb

@@ -1,9 +1,31 @@
 require "delegate"
 
 module WordpressClient
+  # Represents a paginated list of resources.
+  #
+  # @note This class has the full +Array+ interface by using
+  #       +DelegateClass(Array)+. Methods do not show up in the documentation
+  #       unless when manually documented.
   class PaginatedCollection < DelegateClass(Array)
+    # @!method size
+    #   @return [Fixnum] the number of records actually in this "page".
+    #   @see Array#size
+
     attr_reader :total, :current_page, :per_page
 
+    # @!attribute [r] total
+    #   @return [Fixnum] the total hits in the full collection.
+    #   @see #size #size is the size of the current "page".
+
+    # @!attribute [r] current_page
+    #   @return [Fixnum] the current page number, where +1+ is the first page.
+
+    # @!attribute [r] per_page
+    #   @return [Fixnum] the current page size setting, for example +30+.
+
+    # Create a new collection using the passed array +entries+.
+    #
+    # @param entries [Array] the original "page" array
     def initialize(entries, total:, current_page:, per_page:)
       super(entries)
       @total = total
@@ -11,12 +33,15 @@ module WordpressClient
       @per_page = per_page
     end
 
-    #
-    # Pagination methods. Fulfilling will_paginate protocol
-    #
+    # @!group will_paginate protocol
 
     alias total_entries total
 
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    # @return [Fixnum] the total number of pages that can show the {#total}
+    #         entries with {#per_page} records per page. +0+ if no entries.
     def total_pages
       if total.zero? || per_page.zero?
         0
@@ -25,23 +50,53 @@ module WordpressClient
       end
     end
 
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    # @return [Fixnum, nil] the next page number or +nil+ if on last page.
     def next_page
       if current_page < total_pages
         current_page + 1
       end
     end
 
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    # @return [Fixnum, nil] the previous page number or +nil+ if on first page.
     def previous_page
       if current_page > 1
         current_page - 1
       end
     end
 
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    # @return [Boolean] if the current page is out of bounds, e.g. less than 1
+    #                   or higher than {#total_pages}.
     def out_of_bounds?
       current_page < 1 || current_page > total_pages
     end
 
-    # will_paginate < 3.0 has this method
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    #
+    # @note will_paginate < 3.0 has this method, but it's no longer present in
+    #       newer will_paginate.
+    #
+    # Returns the offset of the current page.
+    #
+    # @example First page offset
+    #   collection.per_page # => 20
+    #   collection.current_page # => 1
+    #   collection.offset #=> 0
+    # @example Later offset
+    #   collection.per_page # => 20
+    #   collection.current_page # => 3
+    #   collection.offset #=> 40
+    #
     def offset
       if current_page > 0
         (current_page - 1) * per_page
@@ -49,5 +104,7 @@ module WordpressClient
         0
       end
     end
+
+    # @!endgroup
   end
 end

data/lib/wordpress_client/post.rb

@@ -1,6 +1,9 @@
 require "time"
 
 module WordpressClient
+  # Represents a post in Wordpress.
+  #
+  # @see http://v2.wp-api.org/reference/posts/ API documentation for Post
   class Post
     attr_accessor(
       :id, :slug, :url, :guid, :status,
@@ -9,10 +12,60 @@ module WordpressClient
       :categories, :tags, :meta, :featured_image
     )
 
+    # @!attribute [rw] title_html
+    #   @return [String] the title of the media, HTML escaped
+    #   @example
+    #     post.title_html #=> "Fire & diamonds!"
+
+    # @!attribute [rw] date
+    #   @return [Time, nil] the date of the post, in UTC if available
+
+    # @!attribute [rw] updated_at
+    #   @return [Time, nil] the modification date of the post, in UTC if available
+
+    # @!attribute [rw] guid
+    #   @return [String] the permalink/GUID of the post for internal addressing
+    #   @see #url
+
+    # @!attribute [rw] url
+    #   @return [String] the URL (link) to the post
+
+    # @!attribute [rw] status
+    #   @return ["publish", "future", "draft", "pending", "private", nil] the
+    #           current status of the post, or +nil+ if undetermined
+
+    # @!attribute [rw] categories
+    #   @return [Array[Category]] the {Category Categories} the post belongs to.
+    #   @see Category
+
+    # @!attribute [rw] tags
+    #   @return [Array[Tag]] the {Tag Tags} the post belongs to.
+    #   @see Tag
+
+    # @!attribute [rw] featured_image
+    #   @return [Media, nil] the featured image, as an instance of {Media}
+    #   @see Media
+
+    # @!attribute [rw] meta
+    #   Returns the Post meta, as a +Hash+ of +String => String+.
+    #
+    #   @example
+    #     post.meta # => {"Mood" => "Happy", "reviewed_by" => "user:45"}
+    #
+    #   @return [Hash<String,String>] the post meta, as a Hash.
+    #   @see Category
+    #   @see Client#update_post
+
+    # @!attribute [rw] meta_ids
+    #   @api private
+    #   Backs the {#meta_id_for} method. Used when constructing requests.
+
+    # @api private
     def self.parse(data)
       PostParser.parse(data)
     end
 
+    # Construct a new instance with the given attributes.
     def initialize(
       id: nil,
       slug: nil,
@@ -47,14 +100,32 @@ module WordpressClient
       @meta_ids = meta_ids
     end
 
+    # A list of all category ids for the post.
+    #
+    # You can pass this list, with IDs added or removed, to
+    # {Client#update_post} to change the category list.
+    #
+    # @return [Array[Fixnum]] the id of every category associated with this post
+    # @see Client#update_post
     def category_ids() categories.map(&:id) end
 
+    # A list of all tag ids for the post.
+    #
+    # You can pass this list, with IDs added or removed, to
+    # {Client#update_post} to change the tag list.
+    #
+    # @return [Array[Fixnum]] the id of every tag associated with this post
+    # @see Client#update_post
     def tag_ids() tags.map(&:id) end
 
+    # @return [Fixnum, nil] ID of the featured image associated with the post.
     def featured_image_id
       featured_image && featured_image.id
     end
 
+    # @api private
+    # Used to determine the underlying ID of the different meta keys so they
+    # can be modified by {Client}. You should not use this for anything.
     def meta_id_for(key)
       @meta_ids[key] || raise(ArgumentError, "Post does not have meta #{key.inspect}")
     end

data/lib/wordpress_client/post_parser.rb

@@ -1,4 +1,5 @@
 module WordpressClient
+  # @private
   class PostParser
     include RestParser
 

data/lib/wordpress_client/replace_metadata.rb

@@ -1,6 +1,7 @@
 require "set"
 
 module WordpressClient
+  # @private
   class ReplaceMetadata
     def self.apply(connection, post, meta)
       instance = new(connection, post, meta)

data/lib/wordpress_client/replace_terms.rb

@@ -1,6 +1,7 @@
 require "set"
 
 module WordpressClient
+  # @private
   class ReplaceTerms
     def self.apply_categories(connection, post, category_ids)
       instance = new(

data/lib/wordpress_client/rest_parser.rb

@@ -1,4 +1,8 @@
 module WordpressClient
+  # @private
+  #
+  # Module included in other classes that need to parse result bodies from the
+  # WP API.
   module RestParser
     private
     def rendered(name)

data/lib/wordpress_client/tag.rb

@@ -1,4 +1,6 @@
 module WordpressClient
+  # Represents a tag from Wordpress.
+  # @see Term
   class Tag < Term
   end
 end

data/lib/wordpress_client/term.rb

@@ -1,7 +1,27 @@
 module WordpressClient
+  # @abstract Implement a subclass for the resource type.
+  #
+  # Implementation for the abstract "term" in Wordpress.
+  #
+  # @see Category
+  # @see Tag
   class Term
     attr_reader :id, :name_html, :slug
 
+    # @!attribute [r] id
+    #   @return [Fixnum] The ID of the resource in Wordpress.
+
+    # @!attribute [r] name_html
+    #   @return [String] The name of the resource, HTML encoded.
+    #   @example
+    #     term.name_html #=> "Father & Daughter stuff"
+
+    # @!attribute [r] slug
+    #   @return [String] The slug of the resource in Wordpress.
+
+    # @api private
+    #
+    # Parses a data structure from a WP API response body into this term type.
     def self.parse(data)
       new(
         id: data.fetch("id"),
@@ -16,6 +36,15 @@ module WordpressClient
       @slug = slug
     end
 
+    # @api private
+    # Compares another instance. All attributes in this list must be equal for
+    # the instances to be equal:
+    #
+    # * +id+
+    # * +name_html+
+    # * +slug+
+    #
+    # One must also not be a subclass of the other; they must be the exact same class.
     def ==(other)
       if other.is_a? Term
         other.class == self.class &&
@@ -27,6 +56,7 @@ module WordpressClient
       end
     end
 
+    # Shows a nice representation of the term type.
     def inspect
       "#<#{self.class} ##{id} #{name_html.inspect} (#{slug})>"
     end

data/lib/wordpress_client/version.rb

@@ -1,3 +1,7 @@
 module WordpressClient
-  VERSION = "0.0.1"
+  # Current version of the gem.
+  #
+  # @note This only applies if using a released version. A development build
+  #       would not correspond to this constant.
+  VERSION = "1.0.0"
 end

data/spec/client_spec.rb

@@ -66,7 +66,7 @@ module WordpressClient
           Post, "posts", hash_including(filter: {name: "my-slug"})
         ).and_return [post]
 
-        expect(client.find_by_slug("my-slug")).to eq post
+        expect(client.find_post_by_slug("my-slug")).to eq post
       end
 
       it "raises NotFoundError when trying to find by slug yields no posts" do
@@ -75,7 +75,7 @@ module WordpressClient
         ).and_return []
 
         expect {
-          client.find_by_slug("my-slug")
+          client.find_post_by_slug("my-slug")
         }.to raise_error(NotFoundError, /my-slug/)
       end
     end

data/spec/docker/Dockerfile

@@ -13,11 +13,14 @@ ENV APP_USER admin
 ENV APP_PASS P@ssw0rd
 ENV WP_KEY ILoveFlappyjacks
 
+# Make pretty permalinks work so API is accessible
+COPY htaccess /var/www/html/wordpress/.htaccess
+
 # Restore a copy of a set up database on first boot
 COPY dbdump.sql.gz /tmp/dbdump.sql.gz
 COPY restore-dbdump.sh /tmp/.restore-dbdump.sh
 RUN chmod +x /tmp/.restore-dbdump.sh && \
-    echo "if [ -f /tmp/.restore-dbdump.sh ]; then /tmp/.restore-dbdump.sh; rm -fr /tmp/.restore-dbdump.sh; fi" >> /root/.bashrc
+    echo "if [ -f /tmp/.restore-dbdump.sh ]; then /tmp/.restore-dbdump.sh; rm /tmp/.restore-dbdump.sh; fi" >> /root/.bashrc
 
 ### Install API and API Basic Auth plugins
 
@@ -35,6 +38,3 @@ RUN curl -SL -o /tmp/rest-api.zip https://downloads.wordpress.org/plugin/rest-ap
 RUN curl -SL https://github.com/WP-API/Basic-Auth/archive/master.tar.gz \
   | tar -xzC /var/www/html/wordpress/wp-content/plugins/ \
   && mv /var/www/html/wordpress/wp-content/plugins/Basic-Auth* /var/www/html/wordpress/wp-content/plugins/basic-auth
-
-# Make pretty permalinks work so API is accessible
-COPY htaccess /var/www/html/wordpress/.htaccess

data/spec/docker/README.md

@@ -1,15 +1,47 @@
-# How this was built
+# Docker image for WordpressClient
 
-## dbdump
+Use this docker image to run integration tests, either in this repo or in some client repo where you use the gem.
 
-If you need to regenerate the dbdump, remove the part where the file is copied and restored from the `Dockerfile`, then build and start the image.
+**Note:** This image is not meant for *any* production use. It's meant for integration tests, and nothing else.
+
+## Usage
+
+You need to publish the container's port 80 to whichever port you want your instance on, then set an environment variable for where the server should be accessible from as Wordpress needs to have this stored in the database.
+
+You also need to run it with an interactive terminal in order for it to work.
+
+```bash
+docker run -dit -p 8080:80 -e WORDPRESS_HOST=localhost:8080 hemnet/wordpress_client_test:latest
+```
+
+I you want to see the ouput or access the environment in order to debug an issue, omit the `-d` option. It will boot into a `bash` shell with Apache running in the background. You can also use `docker attach` to attach to a running instance.
+
+**Note:** When you exit a running container, everything stored in it will be kept on disk. It is recommended that you `docker rm` the image when you are done to clean up.
+
+When the instance is up and running, you can log in as an administrator using `test`/`test` as username and password.
+
+## Contents
+
+This image is based on Appcontainer's Wordpress image, which runs Apache, MySQL and PHP5 on CentOS using bash. In addition, a DB dump is restored containing a set up blog so you don't need to do the first installation steps.
+
+* Username `test`
+* Password `test`
+* Plugin `WP-API` is installed
+* Plugin `Basic-Auth` for `WP-API` installed
+* `.htaccess` for Pretty Permalinks is set up so the API works
+
+## Developing the image
+
+### Re-creating DB dump from scratch
+
+If you need to regenerate the DB dump, remove the part where the file is copied and restored from the `Dockerfile`, then build and start the image.
 
 ```bash
-docker build -t wpclient-test .
-docker run -it -p 8181:80 wpclient-test
+docker build -t wordpress_client_test:dev .
+docker run -it -p 8181:80 wordpress_client_test:dev
 ```
 
-You'll get a prompt inside the container. Open your browser and go to the newly booted application (`localhost:8181` if you have native Docker; otherwise go to your `$DOCKER_HOST_IP:8181` URL – see `echo $DOCKER_HOST` in your local shell).
+You'll get a `bash` shell inside the container. Open your browser and go to the newly booted application (`localhost:8181` if you have native Docker; otherwise go to your `DOCKER_HOST_IP:8181` URL – see `echo $DOCKER_HOST` in your local shell).
 
 You'll be greeted by the Wordpress installer. Fill in everything and complete the installation.
 
@@ -22,16 +54,11 @@ mysqldump -u "$MYSQL_USER" --password="$MYSQL_PASS" --host="$MYSQL_HOST" "$MYSQL
 You can then copy the file to your host using the `docker cp` command:
 
 ```bash
-docker ps | grep wpclient-test
+docker ps | grep wordpress_client_test:dev
 # See the container ID or name of your running container
 docker cp THE-CONTAINER-ID:/tmp/dbdump.sql.gz .
 ```
 
-You can then shut down your container by logging out of the container terminal.
-
-Restore the DB loading code from the `Dockerfile`, commit this file to the repo and rebuild everything and verify that Wordpress is still set up correctly when the dump is restored.
+Last step is to update `restore-dbdump.sh` to replace the hard-coded `WORDPRESS_HOST` placeholder with the one you used to generate the DB dump with. This corresponds with `localhost:8181` with native Docker if you followed these commands exactly. If you use `docker-machine`, you need to use your machine IP instead. (See *"Usage"* above)
 
-`spec/docker/restore-dbdump.sh` hard codes an expectation that the IP in your
-datadump is a specfic IP. So you will need to change that hard coded
-expectation to match the new IP used in your data dump. You can find out what
-that IP is by examining the dumo but it is probably the value set in `$DOCKER_HOST`.
+You can then shut down your container by logging out of the container terminal. Restore the DB loading code from the `Dockerfile`, commit this file to the repo and rebuild everything and verify that Wordpress is still set up correctly when the dump is restored.

data/spec/integration/posts_finding_spec.rb

@@ -64,13 +64,13 @@ describe "Posts (finding)" do
   describe "finding by slug" do
     it "finds the matching post" do
       post = client.create_post(title: "Oh hai", slug: "oh-hai")
-      found = client.find_by_slug("oh-hai")
+      found = client.find_post_by_slug("oh-hai")
       expect(found.id).to eq post.id
     end
 
     it "raises NotFoundError when no post can be found" do
       expect {
-        client.find_by_slug("clearly-does-not-exist-anywhere")
+        client.find_post_by_slug("clearly-does-not-exist-anywhere")
       }.to raise_error(WordpressClient::NotFoundError, /clearly/)
     end
 
@@ -79,7 +79,7 @@ describe "Posts (finding)" do
         title: "Updated title that doesn't match slug",
         slug: "original-concise-title",
       )
-      found = client.find_by_slug("original-concise-title")
+      found = client.find_post_by_slug("original-concise-title")
       expect(found.id).to eq post.id
     end
   end

data/spec/support/docker_runner.rb

@@ -9,11 +9,15 @@ module DockerRunner
   end
 
   def image_exists?(name)
-    system("docker images | grep -q '^#{name.shellescape} '")
+    name, tag = name.split(":", 2)
+    matcher = "^#{name} "
+    matcher << "[[:space:]]*#{tag}" if tag
+
+    system("docker images | grep -q #{matcher.shellescape}")
   end
 
   def build_image(name, path: Dir.pwd)
-    system("cd #{path.shellescape} && docker build -t #{name.shellescape} .")
+    system("docker build -t #{name.shellescape} #{path.shellescape}")
   end
 
   def run_container(name, port:, environment: {})

data/spec/support/wordpress_server.rb

@@ -24,6 +24,8 @@ class WordpressServer
   def password() "test" end
 
   private
+  DOCKER_IMAGE_NAME = "hemnet/wordpress_client_test:dev".freeze
+
   def host_with_port
     "#{host}:#{port}"
   end
@@ -62,14 +64,14 @@ class WordpressServer
   end
 
   def build_container_if_missing
-    unless DockerRunner.image_exists?("wpclient-test")
-      DockerRunner.build_image("wpclient-test", path: "spec/docker")
+    unless DockerRunner.image_exists?(DOCKER_IMAGE_NAME)
+      DockerRunner.build_image(DOCKER_IMAGE_NAME, path: "spec/docker")
     end
   end
 
   def start_container
     DockerRunner.run_container(
-      "wpclient-test",
+      DOCKER_IMAGE_NAME,
       port: port,
       environment: {wordpress_host: host_with_port}
     )

data/wordpress_client.gemspec

@@ -24,4 +24,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.3"
   spec.add_development_dependency "webmock", "~> 1.22"
+  spec.add_development_dependency "yard", "~> 0.8.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wordpress_client
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Magnus Bergmark
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-07 00:00:00.000000000 Z
+date: 2015-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -81,6 +81,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.22'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7
 description: A simple client to the Wordpress API.
 email:
 - magnus.bergmark@gmail.com
@@ -89,10 +103,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".codeclimate.yml"
 - ".gitignore"
 - ".hound.yml"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yardopts"
+- Changelog.md
 - Gemfile
 - Guardfile
 - LICENSE
@@ -217,3 +234,4 @@ test_files:
 - spec/support/integration_macros.rb
 - spec/support/wordpress_server.rb
 - spec/tag_spec.rb
+has_rdoc: