apress-documentation 0.4.0

data/app/views/layouts/apress/documentation/_menu.html.haml

@@ -0,0 +1,6 @@
+%ul
+  %li
+    = link_to 'Главная', documentation_url
+  - menu.each do |_key, document|
+    %li
+      = render 'layouts/apress/documentation/menu_item', document: document

data/app/views/layouts/apress/documentation/_menu_item.html.haml

@@ -0,0 +1,7 @@
+= link_to document.title || document.slug, documentation_url(path: document.slug)
+- if document.documents.present?
+  %ul
+    - document.documents.each do |_key, document|
+      %li
+        = render 'layouts/apress/documentation/menu_item',
+                 document: document

data/app/views/layouts/apress/documentation/_sidebar.html.haml

@@ -0,0 +1,2 @@
+%aside.sidebar
+  = render 'layouts/apress/documentation/menu', menu: Apress::Documentation.data

data/app/views/layouts/documentation.html.haml

@@ -0,0 +1,17 @@
+!!!
+%html
+  %head
+    = stylesheet_link_tag 'package/swagger_screen', media: :screen
+    = stylesheet_link_tag 'package/swagger_print', media: :print
+    = stylesheet_link_tag 'package/documentation', media: 'all'
+    = javascript_include_tag 'package/documentation', defer: true
+    :javascript
+      var app = {};
+
+  %body
+    %main
+      - cache 'sidebar' do
+        = render 'layouts/apress/documentation/sidebar'
+
+      %section.content
+        = yield

data/apress-documentation.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'apress/documentation/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'apress-documentation'
+  spec.version       = Apress::Documentation::VERSION
+  spec.authors       = ['Korobicyn Denis']
+  spec.email         = ['deniskorobitcin@gmail.com']
+  spec.summary       = 'apress-documentation'
+  spec.description   = 'apress-documentation'
+  spec.homepage      = 'https://github.com/abak-press/apress-documentation'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'rails', '>= 3.2'
+  spec.add_runtime_dependency 'haml-rails', '>= 0.4'
+  spec.add_runtime_dependency 'swagger-blocks', '>= 1.3'
+  spec.add_runtime_dependency 'rgl'
+
+  spec.add_development_dependency "bundler", ">= 1.14"
+  spec.add_development_dependency "rake", ">= 10.0"
+  spec.add_development_dependency "rspec", ">= 3.0"
+  spec.add_development_dependency 'rspec-rails', '>= 3.2'
+  spec.add_development_dependency 'combustion', '>= 0.5.4'
+  spec.add_development_dependency 'appraisal'
+  spec.add_development_dependency 'simplecov', '>= 0.9'
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency 'test-unit'
+  spec.add_development_dependency 'pry-byebug'
+end

data/config/routes.rb

@@ -0,0 +1,16 @@
+Rails.application.routes.draw do
+  scope path: Apress::Documentation[:path_scope] do
+    scope module: :apress, constraints: Apress::Documentation[:routes_constraints] do
+      scope module: :documentation do
+        get "/documentation/(*path)", to: 'documents#show', as: :documentation
+      end
+
+      scope path: :api do
+        scope module: :documentation do
+          resource :swagger, controller: :swagger_ui, only: :show
+          resource :docs, controller: :swagger, only: :show
+        end
+      end
+    end
+  end
+end

data/dip.yml

@@ -0,0 +1,48 @@
+version: '1'
+
+environment:
+  DOCKER_RUBY_VERSION: 2.2
+  RUBY_IMAGE_TAG: 2.2-latest
+  COMPOSE_FILE_EXT: development
+  RAILS_ENV: test
+  APRESS_GEMS_CREDENTIALS: ""
+
+compose:
+  files:
+    - docker-compose.yml
+    - docker-compose.${COMPOSE_FILE_EXT}.yml
+
+interaction:
+  sh:
+    service: app
+
+  irb:
+    service: app
+    command: bundle exec irb
+
+  bundle:
+    service: app
+    command: bundle
+
+  rake:
+    service: app
+    command: bundle exec rake
+
+  appraisal:
+    service: app
+    command: bundle exec appraisal
+
+  rspec:
+    service: app
+    command: bundle exec appraisal bundle exec rspec
+
+  clean:
+    service: app
+    command: rm -f Gemfile.lock gemfiles/*.gemfile.*
+
+provision:
+  - docker volume create --name bundler_data
+  - dip bundle config --local https://gems.railsc.ru/ ${APRESS_GEMS_CREDENTIALS}
+  - dip clean
+  - dip bundle install
+  - dip appraisal install

data/docker-compose.development.yml

@@ -0,0 +1,18 @@
+version: '2'
+
+services:
+  app:
+    volumes:
+      - .:/app
+      - ../:/localgems
+      - ssh-data:/ssh:ro
+      - bundler-data:/bundle
+
+volumes:
+  bundler-data:
+    external:
+      name: bundler_data
+
+  ssh-data:
+    external:
+      name: ssh_data

data/docker-compose.drone.yml

@@ -0,0 +1,7 @@
+version: '2'
+
+services:
+  app:
+    volumes:
+      - .:/app
+      - /bundle:/bundle

data/docker-compose.yml

@@ -0,0 +1,10 @@
+version: '2'
+
+services:
+  app:
+    image: abakpress/ruby-app:$RUBY_IMAGE_TAG
+    environment:
+      - BUNDLE_PATH=/bundle/$DOCKER_RUBY_VERSION
+      - BUNDLE_CONFIG=/app/.bundle/config
+      - SSH_AUTH_SOCK=/ssh/auth/sock
+    command: bash

data/lib/apress/documentation.rb

@@ -0,0 +1,48 @@
+require 'rails/all'
+require 'haml-rails'
+require 'swagger/blocks'
+require 'rgl/adjacency'
+require 'rgl/dot'
+require 'apress/documentation/extensions/rgl/adjacency'
+require 'apress/documentation/swagger/schema'
+require 'apress/documentation/storage/dependency_graph'
+require 'apress/documentation/storage/swagger_document'
+require 'apress/documentation/storage/document'
+require 'apress/documentation/storage/modules'
+require 'apress/documentation/engine'
+require "apress/documentation/version"
+
+# Public: Основной модуль для использования
+#
+# Содержит методы построения и получения динамически определяемых документов
+module Apress
+  module Documentation
+    def self.modules
+      Apress::Documentation::Storage::Modules.instance
+    end
+
+    def self.add_load_path(path)
+      ActiveSupport.on_load(:documentation) do
+        Dir[File.join(path, '/**/*.rb')].each { |file| require file }
+
+        yield if block_given?
+      end
+    end
+
+    def self.reset!
+      Apress::Documentation::Storage::DependencyGraph.instance.reset!
+      modules.reset!
+    end
+
+    def self.validate_dependencies!
+      Apress::Documentation::Storage::DependencyGraph.instance.validate!
+    end
+
+    class << self
+      extend Forwardable
+
+      def_delegators :modules, :data, :fetch_document, :build
+      def_delegators 'Rails.application.config.documentation', :[], :[]=, :fetch
+    end
+  end
+end

data/lib/apress/documentation/dsl/compilers/base_compiler.rb

@@ -0,0 +1,32 @@
+module Apress
+  module Documentation
+    module Dsl
+      # Private: AbstractClass Базовы класс компилятора DSL
+      #
+      # задает DSL для настройки DSL (Xzibit style)
+      class BaseCompiler
+        # Public: Объект в который будут заполняться поля чере DSL
+        attr_reader :target
+
+        def initialize(target)
+          @target = target
+        end
+
+        # Public: Основной метод, задает какие поля объект DSL-класса будет записивать в target
+        def self.setters(*method_names)
+          method_names.each do |name|
+            send :define_method, name do |value|
+              @target.send("#{name}=", value)
+            end
+          end
+        end
+
+        # Public: Осуществляет исполнение DSL и заполняет нужные поля в target
+        def compile(fields, &block)
+          @target.assign(fields)
+          instance_eval(&block) if block_given?
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/dsl/compilers/document_compiler.rb

@@ -0,0 +1,111 @@
+require_relative 'base_compiler'
+require_relative '../utils/swagger_bind_point_extractor'
+require_relative './mixins/dependable'
+require_relative './mixins/publicity'
+
+module Apress
+  module Documentation
+    module Dsl
+      module Compilers
+        # Private: "Компилирует" блок для объекта класса Document заполняя в нем нужные аттрибуты
+        class DocumentCompiler < BaseCompiler
+          include Apress::Documentation::Dsl::Mixins::Dependable
+          include Apress::Documentation::Dsl::Mixins::Publicity
+          setters :title,
+                  :description,
+                  :business_desc,
+                  :tests
+
+          # Public: метод DSL, Создает документ, осуществляет вложеность документов
+          #
+          # slug - (required), String or Symbol - слаг документа
+          # fields - Hash - позволяет задавать поля через хеш
+          # block - Proc - DSL для настройки полей документа
+          #
+          #  Examples
+          #
+          #    Apress::Documentation.build(:module) do
+          #      document(:html) do
+          #        description 'Описывает все HTMl старницы'
+          #        document(:page) do
+          #          description 'Тут описание только одной'
+          #        end
+          #      end
+          #    end
+          #
+          #    Можно вызывать без блока
+          #    Apress::Documentation.build(:module) do
+          #      document :name, title: :test, description: 'some description'
+          #    end
+          def document(slug, fields = {}, &block)
+            slug = slug.to_s
+            doc = target.documents[slug]
+            doc ||= Apress::Documentation::Storage::Document.new(target.slug + '/' + slug)
+            Storage::DependencyGraph.instance.add_document(doc)
+
+            target.documents[slug] = doc
+            doc.compile(fields, &block)
+          end
+
+          # Public: метод DSL, Создает swagger-описание внутри документа.
+          #
+          # slug - (required), String or Symbol - слаг документа
+          # fields - Hash - позволяет задавать поля через хеш
+          # block - Proc - DSL для настройки полей документа
+          #
+          # Examples
+          #
+          #   Apress::Documentation.build(:module) do
+          #     document(:http_api) do
+          #       description 'Описывает все API модуля'
+          #       swagger_bind('tag_operationId_content') do
+          #         description 'Тут описание только одной'
+          #         swagger_path('api/docs') do
+          #            # Тут вызовы методов Swagger::Blocks
+          #         end
+          #       end
+          #     end
+          #   end
+          #
+          #   Можно вызывать без указания html_id,
+          #   тогда он будет "распознан" из блока автоматически, если это возможно.
+          #   В случае если html_id не был передан и "распознать" html_id невозможно, будет кинуто исключение.
+          #
+          #   Детали "распознования" см. в Apress::Documentation::Dsl::Utils::SwaggerBindPointExtractor
+          #
+          #   Apress::Documentation.build(:module) do
+          #     document(:http_api) do
+          #       description 'Описывает все API модуля'
+          #       swagger_bind do                        # -> будет tag_operationId_content
+          #         description 'Тут описание только одной'
+          #         swagger_path('api/docs') do
+          #           operation :get do
+          #              key :operationId, 'operationId' # -> обязательный вызов для распознавания
+          #              key :tags, ['tag']              # -> обязательный вызов для распознавания
+          #           end
+          #         end
+          #       end
+          #     end
+          #   end
+          def swagger_bind(html_id = nil, fields = {}, &block)
+            html_id = recognize_html_id(html_id, &block)
+            doc = target.swagger_documents[html_id]
+            doc ||= Apress::Documentation::Storage::SwaggerDocument.new(target, html_id)
+            Storage::DependencyGraph.instance.add_document(doc)
+
+            target.swagger_documents[html_id] = doc
+            doc.compile(fields, &block)
+          end
+
+          private
+
+          def recognize_html_id(html_id, &block)
+            html_id ||= Apress::Documentation::Dsl::Utils::SwaggerBindPointExtractor.new.extract(&block)
+            raise "Could not recognize html_id from block" unless html_id
+            html_id.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/dsl/compilers/mixins/dependable.rb

@@ -0,0 +1,31 @@
+module Apress
+  module Documentation
+    module Dsl
+      module Mixins
+        module Dependable
+          # Public: создает зависимости между документами, является частью DSL
+          #
+          # Arguments:
+          #   documents_slugs - Массив полных слагов для документом от которых зависит текущий документ.
+          # Examples:
+          #   Apress::Documentation.build(:module) do
+          #     document(:doc2) do
+          #       depends_on('module/doc1', 'other_model/other_document')
+          #     end
+          #
+          #     document(:doc1)
+          #   end
+          #
+          def depends_on(*documents_slugs)
+            documents_slugs.each do |document_slug|
+              document = Apress::Documentation::Storage::Modules.instance.fetch_document(document_slug)
+              document ||= document_slug
+              Apress::Documentation::Storage::DependencyGraph.instance.add_document(document)
+              Apress::Documentation::Storage::DependencyGraph.instance.add_dependency(@target, document)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/dsl/compilers/mixins/publicity.rb

@@ -0,0 +1,34 @@
+module Apress
+  module Documentation
+    module Dsl
+      module Mixins
+        module Publicity
+          ACCESS_MAPPING = {
+            public: 'Публичный',
+            private: 'Приватный',
+            protected: 'Защищеный'
+          }.freeze
+
+          # Public: указывает уровень доступа документа, является частью DSL
+          #
+          # Arguments:
+          #   level - Symbol, valid values - :public, :private, :protected
+          # Examples:
+          #   Apress::Documentation.build(:module) do
+          #     document(:doc1) do
+          #       publicity :public
+          #     end
+          #   end
+          #
+          def publicity(level)
+            unless ACCESS_MAPPING.keys.include?(level)
+              raise "Неизвестный уровень доступа - #{level}, объявлен в документе #{@target.slug}"
+            end
+
+            @target.publicity = ACCESS_MAPPING[level]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/dsl/compilers/swagger_compiler.rb

@@ -0,0 +1,25 @@
+require_relative 'base_compiler'
+require_relative './mixins/dependable'
+require_relative './mixins/publicity'
+
+module Apress
+  module Documentation
+    module Dsl
+      module Compilers
+        # Private: "Компилирует" блок для объекта класса SwaggerDocument заполняя в нем нужные аттрибуты
+        class SwaggerCompiler < BaseCompiler
+          include Apress::Documentation::Dsl::Mixins::Dependable
+          include Apress::Documentation::Dsl::Mixins::Publicity
+          extend Forwardable
+
+          alias_method :swagger_document, :target
+          setters :business_desc,
+                  :tests
+
+          def_delegators :swagger_document, :swagger_class
+          def_delegators :swagger_class, :swagger_path
+        end
+      end
+    end
+  end
+end