Update usage of info admonitions

rom-rb · Sep 29, 2019 · 5707515 · 5707515
1 parent dd6361a
commit 5707515
Show file tree

Hide file tree

Showing 10 changed files with 44 additions and 39 deletions.
diff --git a/source/4.0/learn/core/combines.html.md b/source/4.0/learn/core/combines.html.md
@@ -24,7 +24,7 @@ which offer lazy loading by default. Since composing data is so quick and easy
 lazy loading is not needed preventing a whole class of issues such as N+1
 query performance problems.
 
-^
+^INFO
   Before you can combine relations an association has to be configured in
   the relations' schema. See [associations](/%{version}/learn/core/associations)
   for more details.
@@ -271,7 +271,7 @@ user_relation
 #      :project_tasks=>[{:id=>3, :project_id=>2}, {:id=>4, :project_id=>2}]}]}
 ```
 
-^
+^INFO
   When adjusting combines, the order of `#combine` and `#node` is important.
   `#node` must come after `#combine` in the call chain otherwise
   the *block* will be ignored and the adjustment will fail

diff --git a/source/4.0/learn/getting-started/core-concepts.html.md b/source/4.0/learn/getting-started/core-concepts.html.md
@@ -89,7 +89,7 @@ To learn more about repositories, how to use them and their role in a system
 developed using ROM, check out the
 [Repositories](/%{version}/learn/repositories) section.
 
-^
+^INFO
   Repositories are completely optional and while they provide powerful features
   for encapsulating data access logic, they may not make sense for some 
   simple CRUD applications or one-off scripts.
@@ -162,7 +162,7 @@ potentially new command types. Furthermore, an adapter can provide extra
 features that are needed to work with a given database type. For example,
 `rom-sql` provides Migration API for managing the schema in a SQL database.
 
-^
+^INFO
   **Remember** all of the abstractions provided by ROM are ultimately there
   to separate any hard dependencies higher up in the application stack. So
   when creating relations, take advantage of that separation by not leaking

diff --git a/source/4.0/learn/introduction/active-record.html.md b/source/4.0/learn/introduction/active-record.html.md
@@ -27,7 +27,7 @@ databases with ROM. Information on installing and configuring rom-sql for your
 database can be found in the
 [SQL](/%{version}/learn/sql) guide.
 
-^
+^INFO
   Examples below assume a configured environment for each
   framework. For ROM examples this means an initialized `ROM::Container` with
   each component registered.
@@ -39,15 +39,14 @@ database can be found in the
   guides.
 ^
 
-^
+^INFO
   Both frameworks have many similar APIs but philosophically they are
   completely different. In this guide, we attempt to highlight these differences
   and provide context for why we chose a different path. That is not to say ROM
   is better than ActiveRecord or vise-versa, it's that they're different and
   each has its own strengths and weaknesses. 
 ^
 
-
 ## Models vs Relations
 
 The first difference is ROM doesn't really have a concept of models. ROM objects
@@ -60,12 +59,14 @@ essentially a data object with attribute readers, coercible to a hash.
 More on ROM Structs later.
 
 <h4 class="text-center">Active Record</h4>
+
 ```ruby
 class User < ApplicationRecord
 end
 ```
 
 <h4 class="text-center">ROM</h4>
+
 ```ruby
 class Users < ROM::Relation[:sql]
   schema(infer: true)
@@ -88,6 +89,7 @@ a relation. A custom type or plain hash can also be used instead, but ROM
 structs offer a fast alternative without having to write a lot of boilerplate.
 
 <h4 class="text-center">Active Record</h4>
+
 ```ruby
 class User < ApplicationRecord
   def first_name
@@ -109,8 +111,8 @@ user.last_name
 #> "Doe"
 ```
 
-
 <h4 class="text-center">ROM</h4>
+
 ```ruby
 class Users < ROM::Relation[:sql]
   struct_namespace Entities
@@ -153,12 +155,12 @@ Once you have a relation, it becomes almost trivial to start querying for
 information in a similar fashion as ActiveRecord. A basic example below:
 
 <h4 class="text-center">Active Record</h4>
+
 ```ruby
 User.where(name: "Jane").first
 #> #<User id: 1, name: "Jane">
 ```
 
-
 <h4 class="text-center">ROM</h4>
 ```ruby
 users_relation.where(name: "Jane").first

diff --git a/source/4.0/learn/sql/index.html.md b/source/4.0/learn/sql/index.html.md
@@ -35,7 +35,7 @@ relied upon for functionality. If <mark>rom-sql</mark> is missing functionality
 that can be accomplished in Sequel then please leave a report in our [issue
 tracker](https://github.com/rom-rb/rom-rb.org/issues).
 
-^
+^INFO
   The SQL Adapter documentation is still being created & revised. If something
   isn't documented or requires more information, please click the  "Provide
   Feedback" buttons at the bottom of the pages and let us know. In the mean time
@@ -65,7 +65,7 @@ require 'rom-sql'
 Once loaded the SQL Adapter will register itself with ROM and become available 
 for immediate use via the `:sql` identifier.
 
-^
+^INFO
   Each database type requires a separate driver gem to also be installed. 
   Be sure to check out the documentation of your preferred database for
   more information.
@@ -591,7 +591,7 @@ are no configuration options supported through the uri. The below
 [Quick Connect](#quick-connect_2) examples should offer enough information on how to connect
 to this type of database.
 
-^
+^INFO
   By default a SQLite in-memory database is restricted to a single connection.
   This is a restriction imposed by SQLite itself and for this reason,
   Sequel sets the maximum number of connections in the connection pool to `1`.

diff --git a/source/5.0/learn/core/combines.html.md b/source/5.0/learn/core/combines.html.md
@@ -24,7 +24,7 @@ which offer lazy loading by default. Since composing data is so quick and easy
 lazy loading is not needed preventing a whole class of issues such as N+1
 query performance problems.
 
-^
+^INFO
   Before you can combine relations an association has to be configured in
   the relations' schema. See [associations](/%{version}/learn/core/associations)
   for more details.
@@ -271,7 +271,7 @@ user_relation
 #      :project_tasks=>[{:id=>3, :project_id=>2}, {:id=>4, :project_id=>2}]}]}
 ```
 
-^
+^INFO
   When adjusting combines, the order of `#combine` and `#node` is important.
   `#node` must come after `#combine` in the call chain otherwise
   the *block* will be ignored and the adjustment will fail

diff --git a/source/5.0/learn/getting-started/core-concepts.html.md b/source/5.0/learn/getting-started/core-concepts.html.md
@@ -89,7 +89,7 @@ To learn more about repositories, how to use them and their role in a system
 developed using ROM, check out the
 [Repositories](/%{version}/learn/repositories) section.
 
-^
+^INFO
   Repositories are completely optional and while they provide powerful features
   for encapsulating data access logic, they may not make sense for some 
   simple CRUD applications or one-off scripts.
@@ -162,7 +162,7 @@ potentially new command types. Furthermore, an adapter can provide extra
 features that are needed to work with a given database type. For example,
 `rom-sql` provides Migration API for managing the schema in a SQL database.
 
-^
+^INFO
   **Remember** all of the abstractions provided by ROM are ultimately there
   to separate any hard dependencies higher up in the application stack. So
   when creating relations, take advantage of that separation by not leaking

diff --git a/source/5.0/learn/getting-started/rails-setup.html.md b/source/5.0/learn/getting-started/rails-setup.html.md
@@ -80,17 +80,19 @@ class UsersController < ApplicationController
 end
 ```
 
-> Accessing the global container directly is considered as a bad practice. The
-> recommended way is to use a DI mechanism to inject specific ROM components as
-> dependencies into your objects.
->
-> For example you can use [dry-container](https://github.com/dryrb/dry-container)
-> and [dry-auto_inject](https://github.com/dryrb/dry-auto_inject) to define
-> your own application container and specify dependencies there to have them
-> automatically injected.
->
-> See [rom-rails-skeleton](https://github.com/solnic/rom-rails-skeleton) for an
-> example of such setup.
+^WARNING
+Accessing the global container directly is considered as a bad practice. The
+recommended way is to use a DI mechanism to inject specific ROM components as
+dependencies into your objects.
+
+For example you can use [dry-container](https://github.com/dryrb/dry-container)
+and [dry-auto_inject](https://github.com/dryrb/dry-auto_inject) to define
+your own application container and specify dependencies there to have them
+automatically injected.
+
+See [rom-rails-skeleton](https://github.com/solnic/rom-rails-skeleton) for an
+example of such setup.
+^
 
 ## Defining Relations
 

diff --git a/source/5.0/learn/http/index.html.md b/source/5.0/learn/http/index.html.md
@@ -41,16 +41,16 @@ When you set up an `HTTP` gateway, you need to specify at the URI. Let's say we
 config = ROM::Configuration.new(:http, uri: "https://api.github.com", handlers: :json)
 ```
 
-^
-Setting up a gateway assumes that all registered relations will use the `uri` as the `base_path` for all requests.
+^INFO
+  Setting up a gateway assumes that all registered relations will use the `uri` as the `base_path` for all requests.
 ^
 
 ## Relations
 
 When you define relations for `HTTP` adapter, you need to specify the schemas as there's no way to infer them.
 
-^
-By defining schemas you tell `ROM` which attributes you're interested in, everything else will be rejected from the original responses.
+^INFO
+  By defining schemas you tell `ROM` which attributes you're interested in, everything else will be rejected from the original responses.
 ^
 
 Here's an example how you could define a relation to fetch organizations from GitHub:
@@ -103,8 +103,8 @@ ROM::HTTP::Handlers.register(:my_handlers,
 
 Then you can use `:my_handlers` when setting up a gateway.
 
-^
-Your custom handlers must be compatible with the required interface. Refer to [the built-in JSON handlers](https://github.com/rom-rb/rom-http/blob/master/lib/rom/http/handlers/json.rb) to get the idea.
+^INFO
+  Your custom handlers must be compatible with the required interface. Refer to [the built-in JSON handlers](https://github.com/rom-rb/rom-http/blob/master/lib/rom/http/handlers/json.rb) to get the idea.
 ^
 
 ## Learn more

diff --git a/source/5.0/learn/introduction/active-record.html.md b/source/5.0/learn/introduction/active-record.html.md
@@ -27,7 +27,7 @@ databases with ROM. Information on installing and configuring rom-sql for your
 database can be found in the
 [SQL](/%{version}/learn/sql) guide.
 
-^
+^INFO
   Examples below assume a configured environment for each
   framework. For ROM examples this means an initialized `ROM::Container` with
   each component registered.
@@ -39,7 +39,7 @@ database can be found in the
   guides.
 ^
 
-^
+^INFO
   Both frameworks have many similar APIs but philosophically they are
   completely different. In this guide, we attempt to highlight these differences
   and provide context for why we chose a different path. That is not to say ROM

diff --git a/source/5.0/learn/sql/index.html.md b/source/5.0/learn/sql/index.html.md
@@ -35,7 +35,7 @@ relied upon for functionality. If <mark>rom-sql</mark> is missing functionality
 that can be accomplished in Sequel then please leave a report in our [issue
 tracker](https://github.com/rom-rb/rom-rb.org/issues).
 
-^
+^INFO
   The SQL Adapter documentation is still being created & revised. If something
   isn't documented or requires more information, please click the  "Provide
   Feedback" buttons at the bottom of the pages and let us know. In the mean time
@@ -45,6 +45,7 @@ tracker](https://github.com/rom-rb/rom-rb.org/issues).
 ^
 
 ## Installing
+
 *Depends on:* `ruby v2.3.0` or greater
 
 To install <mark>rom-sql</mark> add the following to your
@@ -65,7 +66,7 @@ require 'rom-sql'
 Once loaded the SQL Adapter will register itself with ROM and become available 
 for immediate use via the `:sql` identifier.
 
-^
+^INFO
   Each database type requires a separate driver gem to also be installed. 
   Be sure to check out the documentation of your preferred database for
   more information.
@@ -591,18 +592,18 @@ are no configuration options supported through the uri. The below
 [Quick Connect](#quick-connect_2) examples should offer enough information on how to connect
 to this type of database.
 
-^
+^INFO
   By default a SQLite in-memory database is restricted to a single connection.
   This is a restriction imposed by SQLite itself and for this reason,
   Sequel sets the maximum number of connections in the connection pool to `1`.
   Overriding the connection pool limit will result in weird behavior as new
   connections will be to separate memory databases. 
-^
 
 For more information see 
 [Sequel's SQLite](http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-sqlite)
 documentation or for URI file formats see
 [URI Filenames in SQLite](https://www.sqlite.org/uri.html)
+^
 
 #### Quick Connect