shrine 3.0.0.rc → 3.0.0

data/doc/plugins/derivatives.md

@@ -1,4 +1,6 @@
-# Derivatives
+---
+title: Derivatives
+---
 
 The derivatives plugin allows storing processed files ("derivatives") alongside
 the main attached file. The processed file data will be saved together with the
@@ -8,45 +10,6 @@ main attachment data in the same record attribute.
 Shrine.plugin :derivatives
 ```
 
-## Contents
-
-* [API overview](#api-overview)
-* [Creating derivatives](#creating-derivatives)
-  - [Naming processors](#naming-processors)
-  - [Derivatives storage](#derivatives-storage)
-  - [Nesting derivatives](#nesting-derivatives)
-* [Retrieving derivatives](#retrieving-derivatives)
-* [Derivative URL](#derivative-url)
-* [Processing derivatives](#processing-derivatives)
-  - [Dynamic processing](#dynamic-processing)
-  - [Source file](#source-file)
-* [Adding derivatives](#adding-derivatives)
-* [Uploading derivatives](#uploading-derivatives)
-  - [Uploader options](#uploader-options)
-  - [File deletion](#file-deletion)
-* [Merging derivatives](#merging-derivatives)
-  - [Setting derivatives](#setting-derivatives)
-* [Promoting derivatives](#promoting-derivatives)
-* [Removing derivatives](#removing-derivatives)
-  * [Deleting derivatives](#deleting-derivatives)
-* [Miscellaneous](#miscellaneous)
-  * [Without original](#without-original)
-  * [Iterating derivatives](#iterating-derivatives)
-  * [Parsing derivatives](#parsing-derivatives)
-* [Instrumentation](#instrumentation)
-
-## API overview
-
-The interface for managing derivatives is implemented on the `Shrine::Attacher`
-class, and it's layered in the following way:
-
-* [`Attacher#create_derivatives`](#creating-derivatives) – processes, uploads and merges derivatives
-  * [`Attacher#process_derivatives`](#processing-derivatives) – processes derivatives
-  * [`Attacher#add_derivatives`](#adding-derivatives) – uploads and merges derivatives
-    * [`Attacher#upload_derivatives`](#uploading-derivatives) – uploads derivatives
-    * [`Attacher#merge_derivatives`](#merging-derivatives) – merges derivatives
-      * [`Attacher#set_derivatives`](#setting-derivatives) – overrides derivatives
-
 ## Creating derivatives
 
 When you have a file attached, you can generate derivatives from it and save
@@ -164,11 +127,9 @@ class ImageUploader < Shrine
 end
 ```
 ```rb
-# ...
 photo.image_derivatives!(:thumbnails)
 # or
 attacher.create_derivatives(:thumbnails)
-# ...
 ```
 
 ### Derivatives storage
@@ -681,7 +642,9 @@ attacher.derivatives[:two].exists? #=> false
 
 Derivatives are automatically deleted on `Attacher#destroy`.
 
-## Without original
+## Miscellaneous
+
+### Without original
 
 You can store derivatives even if there is no main attached file:
 
@@ -701,7 +664,7 @@ However, note that in this case operations such as promotion and deletion will
 not be automatically triggered in the attachment flow, you'd need to trigger
 them manually as needed.
 
-## Iterating derivatives
+### Iterating derivatives
 
 If you want to iterate over a nested hash of derivatives (which can be
 `Shrine::UploadedFile` objects or raw files), you can use
@@ -727,7 +690,7 @@ end
 #   [:four, 0], #<Shrine::UploadedFile>
 ```
 
-## Parsing derivatives
+### Parsing derivatives
 
 If you want to directly parse derivatives data written to a record attribute,
 you can use `Shrine.derivatives` (counterpart to `Shrine.uploaded_file`):
@@ -773,7 +736,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```
+```plaintext
 Derivatives (2133ms) – {:processor=>:thumbnails, :processor_options=>{}, :uploader=>ImageUploader}
 ```
 
@@ -784,7 +747,7 @@ plugin :derivatives, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```
+```plaintext
 {"name":"derivatives","duration":2133,"processor":"thumbnails","processor_options":{},"uploader":"ImageUploader"}
 ```
 
@@ -794,6 +757,6 @@ Or disable logging altogether:
 plugin :derivatives, log_subscriber: nil
 ```
 
-[default_url]: /doc/plugins/default_url.md#readme
-[entity]: /doc/plugins/entity.md#readme
-[model]: /doc/plugins/model.md#readme
+[default_url]: https://shrinerb.com/docs/plugins/default_url
+[entity]: https://shrinerb.com/docs/plugins/entity
+[model]: https://shrinerb.com/docs/plugins/model

data/doc/plugins/determine_mime_type.md

@@ -1,4 +1,6 @@
-# Determine MIME Type
+---
+title: Determine MIME Type
+---
 
 The [`determine_mime_type`][determine_mime_type] plugin allows you to determine
 and store the actual MIME type of the file analyzed from file content.
@@ -104,7 +106,7 @@ payload:
 
 A default log subscriber is added as well which logs these events:
 
-```
+```plaintext
 MIME Type (33ms) – {:io=>StringIO, :uploader=>Shrine}
 ```
 
@@ -115,7 +117,7 @@ plugin :determine_mime_type, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```
+```plaintext
 {"name":"mime_type","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","uploader":"Shrine"}
 ```
 
@@ -125,7 +127,7 @@ Or disable logging altogether:
 plugin :determine_mime_type, log_subscriber: nil
 ```
 
-[determine_mime_type]: /lib/shrine/plugins/determine_mime_type.rb
+[determine_mime_type]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/determine_mime_type.rb
 [file]: http://linux.die.net/man/1/file
 [Windows equivalent]: http://gnuwin32.sourceforge.net/packages/file.htm
 [ruby-filemagic]: https://github.com/blackwinter/ruby-filemagic

data/doc/plugins/download_endpoint.md

@@ -1,4 +1,6 @@
-# Download Endpoint
+---
+title: Download Endpoint
+---
 
 The [`download_endpoint`][download_endpoint] plugin provides a Rack app for
 downloading uploaded files from specified storages. This can be useful when
@@ -50,7 +52,8 @@ Rails.application.routes.draw do
 end
 ```
 
-*Hint: For shrine versions 2.x -> ensure that you don't include the plugin twice (globally and in your uploader class - see #408)*
+*Hint: For shrine versions 2.x -> ensure that you don't include the plugin
+twice (globally and in your uploader class - see #408)*
 
 ## Calling from a controller
 
@@ -167,4 +170,4 @@ If you want to have more control on download requests, you can use the
 | `:prefix`           | Path prefix prepended to download URLs                                            | `nil`    |
 | `:redirect`         | Whether to redirect to uploaded files on the storage                              | `false`  |
 
-[download_endpoint]: /lib/shrine/plugins/download_endpoint.rb
+[download_endpoint]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/download_endpoint.rb

data/doc/plugins/dynamic_storage.md

@@ -1,4 +1,6 @@
-# Dynamic Storage
+---
+title: Dynamic Storage
+---
 
 The [`dynamic_storage`][dynamic_storage] plugin allows you to register a
 storage using a regex, and evaluate the storage class dynamically depending on
@@ -20,4 +22,4 @@ the bucket "foo". The block is yielded an instance of `MatchData`.
 
 This can be useful in combination with the `default_storage` plugin.
 
-[dynamic_storage]: /lib/shrine/plugins/dynamic_storage.rb
+[dynamic_storage]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/dynamic_storage.rb

data/doc/plugins/entity.md

@@ -1,4 +1,6 @@
-# Entity
+---
+title: Entity
+---
 
 The [`entity`][entity] plugin provides integration for handling attachments on
 immutable structs. It is built on top of the [`column`][column] plugin.
@@ -248,6 +250,6 @@ By default, attachment data is serialized into JSON using the `JSON` standard
 library. If you want to change how data is serialized, see the
 [`column`][column serializer] plugin docs.
 
-[column]: /doc/plugins/column.md#readme
-[entity]: /lib/shrine/plugins/entity.rb
-[column serializer]: /doc/plugins/column.md#serializer
+[entity]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/entity.rb
+[column]: https://shrinerb.com/docs/plugins/column
+[column serializer]: https://shrinerb.com/docs/plugins/column#serializer

data/doc/plugins/form_assign.md

@@ -1,4 +1,6 @@
-# Form Assign
+---
+title: Form Assign
+---
 
 The [`form_assign`][form_assign] plugin allows attaching file from form params
 without a form object.
@@ -50,4 +52,4 @@ attacher.form_assign({ "image" => image, ... }, result: :attributes)
 #=> { :image_data => '{"id":"...","storage":"...","metadata":"..."}', "title" => "...", "description" => "..." }
 ```
 
-[form_assign]: /lib/shrine/plugins/form_assign.rb
+[form_assign]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/form_assign.rb

data/doc/plugins/included.md

@@ -1,4 +1,6 @@
-# Included
+---
+title: Included
+---
 
 The [`included`][included] plugin allows you to hook up to the `.included` hook
 of the attachment module, and call additional methods on the model that
@@ -16,4 +18,4 @@ end
 Photo.include Shrine::Attachment(:image)
 ```
 
-[included]: /lib/shrine/plugins/included.rb
+[included]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/included.rb

data/doc/plugins/infer_extension.md

@@ -1,4 +1,6 @@
-# Infer Extension
+---
+title: Infer Extension
+---
 
 The [`infer_extension`][infer_extension] plugin allows deducing the appropriate
 file extension for the upload location based on the MIME type of the file. This
@@ -68,7 +70,7 @@ payload:
 
 A default log subscriber is added as well which logs these events:
 
-```
+```plaintext
 Extension (5ms) – {:mime_type=>"image/jpeg", :uploader=>Shrine}
 ```
 
@@ -79,7 +81,7 @@ plugin :infer_extension, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```
+```plaintext
 {"name":"extension","duration":5,"mime_type":"image/jpeg","uploader":"Shrine"}
 ```
 
@@ -89,6 +91,6 @@ Or disable logging altogether:
 plugin :infer_extension, log_subscriber: nil
 ```
 
-[infer_extension]: /lib/shrine/plugins/infer_extension.rb
+[infer_extension]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/infer_extension.rb
 [mime-types]: https://github.com/mime-types/ruby-mime-types
 [mini_mime]: https://github.com/discourse/mini_mime

data/doc/plugins/instrumentation.md

@@ -1,4 +1,6 @@
-# Instrumentation
+---
+title: Instrumentation
+---
 
 The [`instrumentation`][instrumentation] plugin publishes events for various
 operations to a centralized notification component. In addition to that, it
@@ -32,7 +34,7 @@ uploaded_file.exists?
 uploaded_file.download
 uploaded_file.delete
 ```
-```
+```plaintext
 Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
 Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
 Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
@@ -185,6 +187,6 @@ Shrine.subscribe(:my_event) do |event|
 end
 ```
 
-[instrumentation]: /lib/shrine/plugins/instrumentation.rb
+[instrumentation]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/instrumentation.rb
 [ActiveSupport::Notifications]: https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html
 [dry-monitor]: https://github.com/dry-rb/dry-monitor

data/doc/plugins/keep_files.md

@@ -1,4 +1,6 @@
-# Keep Files
+---
+title: Keep Files
+---
 
 The [`keep_files`][keep_files] plugin prevents file deletion when the attacher
 is about to destroy currently attached or previously attached file. This
@@ -8,5 +10,10 @@ general any scenario where you need to track history.
 ```rb
 plugin :keep_files
 ```
+```rb
+photo.image #=> #<Shrine::UploadedFile>
+photo.destroy
+photo.image.exists? #=> true
+```
 
-[keep_files]: /lib/shrine/plugins/keep_files.rb
+[keep_files]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/keep_files.rb

data/doc/plugins/metadata_attributes.md

@@ -1,4 +1,6 @@
-# Metadata Attributes
+---
+title: Metadata Attributes
+---
 
 The [`metadata_attributes`][metadata_attributes] plugin allows you to sync
 attachment metadata to additional record attributes. You can provide a hash of
@@ -57,5 +59,5 @@ photo.original_filename #=> "nature.jpg"
 Any metadata attributes that were declared but are missing on the record will
 be skipped.
 
-[metadata_attributes]: /lib/shrine/plugins/metadata_attributes.rb
-[entity]: /doc/plugins/entity.md#readme
+[metadata_attributes]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/metadata_attributes.rb
+[entity]: https://shrinerb.com/docs/plugins/entity

data/doc/plugins/mirroring.md

@@ -1,4 +1,6 @@
-# Mirroring
+---
+title: Mirroring
+---
 
 The [`mirroring`][mirroring] plugin enables replicating uploads and deletes to
 other storages. This can be useful for setting up a backup storage, or when
@@ -113,4 +115,4 @@ file.delete                      # delete from :store
 file.mirror_delete_background    # spawn mirror delete background job
 ```
 
-[mirroring]: /lib/shrine/plugins/mirroring.rb
+[mirroring]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/mirroring.rb

data/doc/plugins/model.md

@@ -1,4 +1,6 @@
-# Model
+---
+title: Model
+---
 
 The [`model`][model] plugin provides integration for handling attachment on
 mutable structs. It is built on top of the [`entity`][entity] plugin.
@@ -198,6 +200,6 @@ By default, attachment data is serialized into JSON using the `JSON` standard
 library. If you want to change how data is serialized, see the
 [`column`][column serializer] plugin docs.
 
-[model]: /lib/shrine/plugins/model.rb
-[entity]: /doc/plugins/entity.md#readme
-[column serializer]: /doc/plugins/column.md#serializer
+[model]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/model.rb
+[entity]: https://shrinerb.com/docs/plugins/entity
+[column serializer]: https://shrinerb.com/docs/plugins/column#serializer

data/doc/plugins/module_include.md

@@ -1,4 +1,6 @@
-# Module Include
+---
+title: Module Include
+---
 
 The [`module_include`][module_include] plugin allows you to extend Shrine's
 core classes for the given uploader with modules/methods.
@@ -39,4 +41,4 @@ end
 The above defines an additional `#<attachment>_size` method on the attachment
 module, which is what is included in your model.
 
-[module_include]: /lib/shrine/plugins/module_include.rb
+[module_include]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/module_include.rb

data/doc/plugins/multi_cache.md

@@ -1,4 +1,6 @@
-# Multi Cache
+---
+title: Multi Cache
+---
 
 The [`multi_cache`][multi_cache] plugin allows an attacher to accept files from
 additional temporary storages.
@@ -19,4 +21,4 @@ photo.image = { "id" => "...", "storage" => "cache_two", "metadata" => { ... } }
 photo.image.storage_key #=> :cache_two
 ```
 
-[multi_cache]: /lib/shrine/plugins/multi_cache.rb
+[multi_cache]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/multi_cache.rb

data/doc/plugins/persistence.md

@@ -1,4 +1,6 @@
-# Persistence
+---
+title: Persistence
+---
 
 This is an internal plugin that provides uniform persistence interface across
 different persistence plugins (e.g. [`activerecord`][activerecord],
@@ -85,5 +87,5 @@ attacher.attach(io)
 attacher.persist # saves the underlying record
 ```
 
-[activerecord]: /doc/plugins/activerecord.md#readme
-[sequel]: /doc/plugins/sequel.md#readme
+[activerecord]: https://shrinerb.com/docs/plugins/activerecord
+[sequel]: https://shrinerb.com/docs/plugins/sequel

data/doc/plugins/presign_endpoint.md

@@ -1,4 +1,6 @@
-# Presign Endpoint
+---
+title: Presign Endpoint
+---
 
 The [`presign_endpoint`][presign_endpoint] plugin provides a Rack endpoint
 which generates the URL, fields, and headers that can be used to upload files
@@ -11,6 +13,8 @@ more.
 plugin :presign_endpoint
 ```
 
+## Setup
+
 The plugin adds a `Shrine.presign_endpoint` method which, given a storage
 identifier, returns a Rack application that accepts GET requests and generates
 a presign for the specified storage. You can run this Rack application inside
@@ -157,7 +161,7 @@ Shrine.presign_endpoint(:cache, presign_location: "${filename}")
 Shrine.presign_response(:cache, env, presign_location: "${filename}")
 ```
 
-[presign_endpoint]: /lib/shrine/plugins/presign_endpoint.rb
+[presign_endpoint]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/presign_endpoint.rb
 [Uppy]: https://uppy.io
 [Amazon S3]: https://aws.amazon.com/s3/
 [Google Cloud Storage]: https://cloud.google.com/storage/

data/doc/plugins/pretty_location.md

@@ -1,4 +1,6 @@
-# Pretty Location
+---
+title: Pretty Location
+---
 
 The [`pretty_location`][pretty_location] plugin attempts to generate a nicer
 folder structure for uploaded files.
@@ -13,7 +15,7 @@ generated locations will typically look like this:
 
 ```rb
 "user/564/avatar/thumb-493g82jf23.jpg"
-# :model/:id/:attachment/:version-:uid.:extension
+# :model/:id/:attachment/:derivative-:uid.:extension
 ```
 
 By default if a record class is inside a namespace, only the "inner" class name
@@ -62,4 +64,4 @@ def generate_location(io, record: nil, **context)
 end
 ```
 
-[pretty_location]: /lib/shrine/plugins/pretty_location.rb
+[pretty_location]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/pretty_location.rb