brainstem 1.0.0.pre.1 → 1.0.0

data/bin/brainstem

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$:.push File.expand_path(File.join('..', '..', 'lib'), __FILE__)
+require 'brainstem/cli'
+
+Brainstem::Cli.call(ARGV)

data/brainstem.gemspec

@@ -17,6 +17,8 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Brainstem::VERSION
 
+  gem.executables   << 'brainstem'
+
   gem.add_dependency "activerecord", ">= 4.1"
   gem.add_dependency "activesupport", ">= 4.1"
 

data/docs/api_doc_generator.markdown

@@ -0,0 +1,175 @@
+# API Doc Generator: Developer's Guide
+
+This documentation explains the intricacies of Brainstem's built-in API
+documentation generation capabilities. For brevity, we refer to this
+particular application as 'docgen'.
+
+## Execution
+
+`bundle exec brainstem generate [ARGS]`
+
+## Customizing Output
+
+#### Making Small Customizations to the Existing Formatters
+
+It is easy to make small customizations to the formatters simply by subclassing
+them, customizing behaviour as you'd like, and then registering over top of an
+existing formatter.
+
+For instance, if you wanted to add a horizontal rule after an endpoint's title:
+
+```ruby
+# config/initializers/brainstem.rb
+require 'brainstem/api_docs/formatters/markdown/endpoint_formatter'
+
+class MyEndpointFormatter < Brainstem::ApiDocs::Formatters::Markdown::EndpointFormatter
+  def format_title!
+    super
+    output << md_hr
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:endpoint][:markdown] = MyFormatter.method(:call)
+```
+
+You can refer to [all the formatters](../lib/brainstem/api_docs/formatters) to
+see what is possible.
+
+#### Adding Custom Formats
+
+Do exactly as above, but instead of declaring it as an existing formatter,
+declare the formatter as one of your own choosing:
+
+```ruby
+Brainstem::ApiDocs::FORMATTERS[:endpoint][:my_format] = MyFormatter.method(:call)
+```
+
+Instead of choosing to inherit from an existing format, you can choose also to
+inherit from `Brainstem::ApiDocs::Formatters::AbstractFormatter` as well.
+
+Note that formatters at this time make concrete references to their own format,
+so if you decide to inherit from existing formatters, you will have to make
+sure these references are changed appropriately.
+
+#### Accessing sibling data from formatters
+
+A formatter formats a wrapping object which serves as a viewmodel to an actual
+entity in your application, such as an `ActionController::Base` or a
+`Brainstem::Presenter`. There are also additional wrapping objects which hold
+collections of these singular wrappers.
+
+These wrappers include the following:
+
+- `Brainstem::ApiDocs::Presenter`
+- `Brainstem::ApiDocs::Endpoint`
+- `Brainstem::ApiDocs::Controller`
+- `Brainstem::ApiDocs::PresenterCollection`
+- `Brainstem::ApiDocs::EndpointCollection`
+- `Brainstem::ApiDocs::Controller`
+
+In some situations, you may want to include documentation for adjacent or or
+similar but unrelated wrapper object. Each of these wrapping objects has a
+method called `find_by_class`, which can return these adjacent objects.
+
+At the moment, finding the following is supported:
+
+- `Presenter`:
+    - find by `target_class`, e.g.
+        - `presenter = find_by_class(association.target_class)`
+        - `presenter = find_by_class(User)`
+
+The object responsible for the lookup functionality is the
+`Brainstem::ApiDocs::Resolver`, which can be reopened if necessary to provide
+further lookups.
+
+#### Adding Additional Configurable Options
+
+The `Brainstem::ApiDocs` module serves double-duty as the receptacle for
+configuration information, and is used throughout the docgen application in
+order to provide alternatives to defaults.
+
+This can be very handy in any of your customizations, and it is relatively easy
+to add, so long as your configuration is used after the host application is
+booted up (see [Phases](#phases)).  Simply re-open the module in your
+initializer, add your desired `config_accessor`, and refer to the constant in
+your formatters:
+
+```ruby
+# config/initializers/brainstem.rb
+
+module Brainstem
+  module ApiDocs
+    config_accessor(:my_config_option) { false }
+  end
+end
+```
+
+```ruby
+# my_formatter.rb
+
+Brainstem::ApiDocs.my_config_option
+```
+
+## Architectural Overview
+
+### Primary Phases
+
+1. ApiDocs namespace and required classes are loaded.
+2. Host application is loaded and required information is extracted
+   (introspection).
+3. Information is repackaged into wrapping objects (atlas creation).
+4. Sink interrogates atlas for specific formatted wrappers (serialization) and
+   persists serialized data to disk (persistence).
+
+
+### Detailed Overview
+
+![DocGen overview](./docgen.png)
+
+
+1. `Brainstem::CLI::GenerateApiDocsCommand` instantiates a builder and a sink,
+   and hands the output of the builder to the sink, which serializes and stores
+   the input somewhere. It also merges the options given to it on the command
+   line with the default options defined in `Brainstem::ApiDocs`.
+2. `Brainstem::ApiDocs::Builder` is responsible for retrieving information from
+   the host application to be exposed to a sink through a
+   `Brainstem::ApiDocs::Introspectors::AbstractIntrospector` subclass. It wraps
+   this information in more friendly and documentable ways, producing a series
+   of collections that can be iterated or reduced from which to produce
+   documentation. It exposes this data through its `atlas` method, which is an
+   instance of `Brainstem::ApiDocs::Atlas`.
+3. `Brainstem::ApiDocs::Introspectors::AbstractIntrospector` defines an
+   interface for objects to return data from the host application. Provided
+   with Brainstem is an implementation of
+   `Brainstem::ApiDocs::Introspectors::RailsIntrospector`, which can be used to
+   extract the required information from a Rails 4 application.
+4. `Brainstem::ApiDocs::Atlas` is an object which receives the data from an
+introspector and transforms it into a series of collections useful for
+producing documentation. It does so by wrapping domain entities and providing
+intelligent interfaces on these collections by which to mutate them. It wraps:
+    - Routes into `Brainstem::ApiDocs::Endpoint` objects, and these into a
+      `Brainstem::ApiDocs::EndpointCollection`;
+    - Controllers into `Brainstem::ApiDocs::Controller` objects, and these into
+      a `Brainstem::ApiDocs::ControllerCollection`;
+    - Presenters into `Brainstem::ApiDocs::Presenter` objects, and these into a
+      `Brainstem::ApiDocs::PresenterCollection`.
+5. Each of these collection and entity objects includes
+   `Brainstem::Concerns::Formattable`, which enables them to be formatted by
+   passing them `formatted_as(format, options)`. Formatters inherit from
+   `Brainstem::ApiDocs::Formatters::AbstractFormatter`, are loaded by
+   `Cerebellum::ApiDocs`, and are stored by self-assigned type. Some or all of
+   these formatters may be provided for this type, depending on the desired
+   behaviour. Brainstem includes an implementation of a `Markdown` formatter,
+   stored under the type `:markdown`, and has a
+   `Brainstem::ApiDocs::Formatters::Markdown::EndpointCollectionFormatter` as
+   well as an `Endpoint-`, `Controller-`, and `PresenterFormatter`. Note that
+   there is not a `ControllerCollectionFormatter`, nor a
+   `PresenterCollectionFormatter` included: this is because the Sink shares
+   partial responsibility for collection formatting, and in the case of the
+   `Brainstem::ApiDocs::Sinks::ControllerPresenterMultifileSink`, outputs each
+   controller and presenter as its own file, rather than as a concatenated
+   collection.
+6. This sink, having received an instance of the `Atlas`, is responsible for
+   serializing&mdash;primarily invoking formatting&mdash;and then outputting
+   the result somewhere, whether to `$stdout`, a file or files on disk, or a
+   remote location.

data/docs/brainstem_executable.markdown

@@ -0,0 +1,32 @@
+# Brainstem Command-line Utility
+
+## Usage
+
+Usage: `brainstem SUBCOMMAND options`
+
+e.g. `brainstem generate --markdown`
+
+Get help by running `brainstem help generate`, or `brainstem generate --help`.
+
+
+## Brainstem Developer Overview
+
+![Brainstem Executable Diagram](./executable.png)
+
+1. The `brainstem` executable instantiates and invokes `Brainstem::Cli`.
+2. `Brainstem::Cli` holds a map of acceptable subcommands and the objects that
+   contain their logic. It also knows how to extract options and invoke
+   execution of these objects, so long as they provide the interface specified
+   in `Brainstem::CLI::AbstractCommand`.
+3. `Brainstem::CLI::AbstractCommand` is an interface whose descendants define
+   an entry point into the application logic. They should expose an option
+   parser through their `option_parser` method, one which mutates the `options`
+   instance method. The parser is evaluated before the instance of the command
+   is `call`ed.
+
+#### Specific Commands
+
+- `Brainstem::CLI::GenerateApiDocsCommand` contains the application logic to
+  generate the API docs annotated by Brainstem. See the [Api Doc Generator
+  documentation](./api_doc_generator.markdown) for more info.
+

data/docs/docgen_ascii.txt

@@ -0,0 +1,63 @@
+Load the following rows into asciiflow.com to edit:
+
+
+
++----------------------------------------+            +-----------------------------+            +---------------------------------------------------------+
+| Brainstem::CLI::GenerateApiDocsCommand +------+-----> Brainstem::ApiDocs::Builder +-------+----> Brainstem::ApiDocs::Introspectors::AbstractIntrospector <-----+
++----------------------------------------+      |     +-----------------------------+       |    +---------------------------------------------------------+     | U
+                                                |                                           |    |                                                               | S
+                                                |                                           |    |    +------------------------------------------------------+   | E
+                                                |                                           |    +----> Brainstem::ApiDocs::Introspectors::RailsIntrospector <---+ S
+                                                |                                           |         +------------------------------------------------------+   |
+                                                |                                           |                                                                    |
+                                                |                                           |                               +------------------------------------+
+                                                |                                           |                               |
+                                                |                                           |    +--------------------------++            +----------------------------------------+
+                                                |                                           +----> Brainstem::ApiDocs::Atlas +------------> Brainstem::ApiDocs::AbstractCollection |
+                                                |                                           |    +------------------------^--+            +----------------------------------------+
+                                                |                                           |                             |               |
+                                                |                                           |                             |               |    +----------------------------------------+             +------------------------------+
+                                                |                                           |                             |               +----> Brainstem::ApiDocs::EndpointCollection +---+---------> Brainstem::ApiDocs::Endpoint +---+
+                                                |                                           |                             |               |    +----------------------------------------+   |         +------------------------------+   |
+                                                |                                           |                             |               |                                                 |                                            |
+                                                |                                           |                             |               |    +------------------------------------------+ |         +--------------------------------+ |
+                                                |                                           |                             |               +----> Brainstem::ApiDocs::ControllerCollection +-----------> Brainstem::ApiDocs::Controller +---+
+                                                |                                           |                             |               |    +------------------------------------------+ |         +--------------------------------+ | |
+                                                |                                           |                             |               |                                                 |                                            | |
+                                                |                                           |                             |               |    +-----------------------------------------+  |         +-------------------------------+  | |
+                                                |                                           |                             |               +----> Brainstem::ApiDocs::PresenterCollection +------------> Brainstem::ApiDocs::Presenter +------+
+                                                |                                           |                             |                    +-----------------------------------------+  |         +-------------------------------+  | | |
+                                                |                                           |                             |                                                                 |                                            | | |
+                                                |                                           |                             +-------------------------------------------+                     |                                            | | |
+                                                |                                           |                                                                         | U                   |                                            | | |
+                                                |                                           |    +-----------------------------------------+                          | S                   |                                            | | | U
+                                                |                                           +----> Brainstem::ApiDocs::Sinks::AbstractSink +--------------------------> E                   |                                            | | | S
+                                                |                                                +-----------------------------------------+                          | S                   |                                            | | | E
+                                                |                                                |                                                                    |                     |                                            | | | S
+                                                |                                                |    +-------------------------------------------------------------+ |                     |                                            | | |
+                                                |                                                +----> Brainstem::ApiDocs::Sinks::ControllerPresenterMultifileSink +-+                     |                                            | | |
+                                                |                                                     +-------------------------------------------------------------+                       |                                            | | |
+                                                |                                                                                                                                           |                                            | | |
+                                                |                                                                                                                                           |                                            | | |
+                                                |                                                                                                                                           |                                            | | |
+                                                |                                                                                                                                           |                                            | | |
+                                                |                                                                                                                                           |                                            | | |
+                                                |     +--------------------+                     +---------------------------------------------------+                                      |                                            | | |
+                                                +-----> Brainstem::ApiDocs +---------------------> Brainstem::ApiDocs::Formatters::AbstractFormatter |                                      |                                            | | |
+                                                      +--------------------+                     +---------------------------------------------------+                                      |                                            | | |
+                                                                                                 |                                                                                          |                                            | | |
+                                                                                                 |    +-----------------------------------------------------------------------+             |                                            | | |
+                                                                                                 +----> Brainstem::ApiDocs::Formatters::Markdown::EndpointCollectionFormatter <-------------+                                            | | |
+                                                                                                 |    +-----------------------------------------------------------------------+                                                          | | |
+                                                                                                 |                                                                                                                                       | | |
+                                                                                                 |    +-------------------------------------------------------------+                                                                    | | |
+                                                                                                 +----> Brainstem::ApiDocs::Formatters::Markdown::EndpointFormatter <--------------------------------------------------------------------+ | |
+                                                                                                 |    +-------------------------------------------------------------+                                                                      | |
+                                                                                                 |                                                                                                                                         | |
+                                                                                                 |    +---------------------------------------------------------------+                                                                    | |
+                                                                                                 +----> Brainstem::ApiDocs::Formatters::Markdown::ControllerFormatter <--------------------------------------------------------------------+ |
+                                                                                                 |    +---------------------------------------------------------------+                                                                      |
+                                                                                                 |                                                                                                                                           |
+                                                                                                 |    +--------------------------------------------------------------+                                                                       |
+                                                                                                 +----> Brainstem::ApiDocs::Formatters::Markdown::PresenterFormatter <-----------------------------------------------------------------------+
+                                                                                                      +--------------------------------------------------------------+

data/docs/executable_ascii.txt

@@ -0,0 +1,10 @@
+Load the following rows into asciiflow.com to edit:
+
+
++------------------------+       +----------------+          +---------------------------------+
+| brainstem (executable) +-------> Brainstem::Cli +----------> Brainstem::CLI::AbstractCommand |
++------------------------+       +----------------+          ++--------------------------------+
+                                                              |
+                                                              |  +----------------------------------------+
+                                                              +--> Brainstem::CLI::GenerateApiDocsCommand |
+                                                                 +----------------------------------------+

data/lib/brainstem/api_docs.rb

@@ -0,0 +1,146 @@
+require 'active_support/configurable'
+
+module Brainstem
+  module ApiDocs
+    include ActiveSupport::Configurable
+
+    config_accessor(:write_path) do
+      File.expand_path("./brainstem_docs")
+    end
+
+
+    #
+    # Defines the naming pattern of each controller documentation file.
+    #
+    # The following tokens will be substituted:
+    #
+    # - {{namespace}} : the namespace of the controller underscored,
+    #                   i.e. 'api/v1'
+    # - {{name}}      : the underscored name of the controller without
+    #                   'controller'
+    # - {{extension}  : the specified file extension
+    #
+    # @see #output_extension
+    #
+    config_accessor(:controller_filename_pattern) do
+      File.join("endpoints", "{{name}}.{{extension}}")
+    end
+
+
+    #
+    # Defines the naming pattern of each presenter documentation file.
+    #
+    # The following tokens will be substituted:
+    #
+    # - {{name}} : the demodulized underscored name of the presenter
+    # - {{extension} : the specified file extension
+    #
+    # @see #output_extension
+    #
+    config_accessor(:presenter_filename_pattern) do
+      File.join("objects", "{{name}}.{{extension}}")
+    end
+
+
+    #
+    # Defines the naming pattern for the relative link to each controller documentation file.
+    #
+    # The following tokens will be substituted:
+    #
+    # - {{name}} : the underscored name of the controller without 'controller'
+    # - {{extension} : the specified file extension
+    #
+    # @see #output_extension
+    #
+    config_accessor(:controller_filename_link_pattern) do
+      controller_filename_pattern
+    end
+
+
+    #
+    # Defines the naming pattern for the relative link to each presenter documentation file.
+    #
+    # The following tokens will be substituted:
+    #
+    # - {{name}} : the demodulized underscored name of the presenter
+    # - {{extension} : the specified file extension
+    #
+    # @see #output_extension
+    #
+    config_accessor(:presenter_filename_link_pattern) do
+      presenter_filename_pattern
+    end
+
+
+    #
+    # Defines the extension that should be used for output files.
+    #
+    # Excludes the '.'.
+    #
+    config_accessor(:output_extension) { "markdown" }
+
+
+    #
+    # Defines the class that all presenters should inherit from / be drawn
+    # from.
+    #
+    # Is a string because most relevant classes are not loaded until much
+    # later.
+    #
+    # @see Brainstem::ApiDocs::RailsIntrospector#base_presenter_class=
+    #
+    config_accessor(:base_presenter_class) do
+      "::Brainstem::Presenter"
+    end
+
+
+    #
+    # Defines the class that all controllers should inherit from / be drawn
+    # from.
+    #
+    # Is a string because most relevant classes are not loaded until much
+    # later.
+    #
+    # @see Brainstem::ApiDocs::RailsIntrospector#base_presenter_class=
+    #
+    config_accessor(:base_controller_class) do
+      "::ApplicationController"
+    end
+
+
+    #
+    # If associations on a presenter have no description, i.e. no documentation,
+    # should they be documented anyway?
+    #
+    config_accessor(:document_empty_presenter_associations) { true }
+
+
+    #
+    # If filters on a presenter have no `:info` key, i.e. no documentation,
+    # should they be documented anyway?
+    #
+    config_accessor(:document_empty_presenter_filters) { true }
+
+
+
+    FORMATTERS = {
+
+      # Formatter for entire response
+      document:    {},
+
+      # Formatters for collections
+      controller_collection: {},
+      endpoint_collection:   {},
+      presenter_collection:  {},
+
+      # Formatters for individual entities
+      controller:  {},
+      endpoint:    {},
+      presenter:   {},
+
+    }
+  end
+end
+
+formatter_path = File.expand_path('../formatters/**/*.rb', __FILE__)
+Dir.glob(formatter_path).each { |f| require f }