apress-documentation 0.4.0

data/lib/apress/documentation/dsl/document.rb

@@ -0,0 +1,14 @@
+require_relative 'compilers/document_compiler'
+
+module Apress
+  module Documentation
+    module Dsl
+      module Document
+        # Public: Подключает DSL в класс данных документа
+        def compile(fields = {}, &block)
+          Apress::Documentation::Dsl::Compilers::DocumentCompiler.new(self).compile(fields, &block)
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/dsl/modules.rb

@@ -0,0 +1,40 @@
+module Apress
+  module Documentation
+    module Dsl
+      module Modules
+        # Protected: Точка входа для построения DS
+        # используется через делегацию в модуле Apress::Documentation
+        #
+        #
+        # module_slug - Symbol - слаг модуля
+        # fields - Hash(optional, default - {}) - поля для установки в короткой записи
+        #          (например, Apress::Documentation.build(:slug, title: 'name'))
+        # &block - Proc(optional) - вызовы DSL методов
+        #
+        # Examples
+        #
+        #   Apress::Documentation.build(:module) do
+        #     name 'some module'
+        #     description 'tests'
+        #   end
+        #
+        #   Apress::Documentation.build(:module) do
+        #     document(:some, title: 'Some doc') do
+        #       description 'Тут вставить описание'
+        #       publicity 'Публичное'
+        #     end
+        #   end
+        #
+        def build(module_slug, fields = {}, &block)
+          module_slug = module_slug.to_s
+          document = self[module_slug]
+          document ||= Apress::Documentation::Storage::Document.new(module_slug)
+          Apress::Documentation::Storage::DependencyGraph.instance.add_document(document)
+          self << document
+
+          document.compile(fields, &block)
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/dsl/swagger_document.rb

@@ -0,0 +1,14 @@
+require_relative 'compilers/swagger_compiler'
+
+module Apress
+  module Documentation
+    module Dsl
+      module SwaggerDocument
+        # Public: Подключает DSL в класс данных swagger-описания
+        def compile(fields = {}, &block)
+          Apress::Documentation::Dsl::Compilers::SwaggerCompiler.new(self).compile(fields, &block)
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/dsl/utils/swagger_bind_point_extractor.rb

@@ -0,0 +1,37 @@
+module Apress
+  module Documentation
+    module Dsl
+      module Utils
+        # Private: "Распознает" идентификатор html-tag'а в SwaggerUI по переданному блоку Swagger::Blocks,
+        # в который будет вставлена дополнительная информация из SwaggerDocument.
+        #
+        # Идея: Выполнить блок DSL swagger_path из Swagger::Blocks без вызовов реальных методов.
+        #
+        # Алгоритм:
+        #   - Выполняем переданный блок от swagger_path, пропуская неизвестные методы
+        #   - как только нашли первый вызов "key :operationId, value", запоминаем value
+        #   - тоже самое для key :tags, [value]
+        #   - если после выполнения блока оба значения заданы (@tag, @operation_id) возвращаем результат
+        class SwaggerBindPointExtractor
+          def extract(&block)
+            instance_eval(&block)
+            "#{@tag}_#{@operation_id}" if @tag && @operation_id
+          end
+
+          def method_missing(name, *args, &block)
+            if block_given?
+              instance_eval(&block)
+            elsif name.to_s == 'key'
+              case args[0]
+              when :operationId
+                @operation_id ||= args[1]
+              when :tags
+                @tag ||= args[1].try(:first)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/engine.rb

@@ -0,0 +1,16 @@
+module Apress
+  module Documentation
+    class Engine < Rails::Engine
+      config.autoload_paths += [
+        config.root.join('app', 'controllers', 'concerns'),
+        config.root.join('app', 'presenters')
+      ]
+
+      config.documentation = {path_scope: nil, routes_constraints: {domain: :current}}
+
+      initializer "apress-documentation", before: :load_init_rb do |app|
+        RGL::DirectedAdjacencyGraph.include Apress::Documentation::Extensions::RGL::Adjacency
+      end
+    end
+  end
+end

data/lib/apress/documentation/extensions/rgl/adjacency.rb

@@ -0,0 +1,18 @@
+module Apress
+  module Documentation
+    module Extensions
+      module RGL
+        module Adjacency
+          # Private: Расширение графа для замены вершины на новую
+          def replace_vertex(old_v, new_v)
+            @vertices_dict[new_v] = @vertices_dict.delete(old_v)
+
+            @vertices_dict.each_value do |list|
+              list.add(new_v) if list.delete?(old_v)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/storage/base_storage.rb

@@ -0,0 +1,88 @@
+module Apress
+  module Documentation
+    module Storage
+      # Private: AbstractClass, Базовый класс хранилища
+      #
+      # описывает методы аттрибутов для сериализации в json формата:
+      # {
+      #   {
+      #     "attr_0": send(:attr_0),
+      #     "attr_1": send(:attr_1),
+      #     ....
+      #   }
+      # }
+      class BaseStorage
+        # Public: Составной слаг, используется как URL
+        attr_reader :slug
+
+        def self.json_attr_names
+          @json_attr_names ||= []
+        end
+
+        # Public: Задает аттрибуты для сериализации в json
+        def self.json_attr(*method_names)
+          json_attr_names.concat(method_names.map(&:to_s))
+
+          attr_accessor(*method_names)
+        end
+
+        # Public: Сериализует объект в JSON
+        def as_json(options = {})
+          self.class.json_attr_names.each_with_object({}) do |attr_name, json|
+            value = send(attr_name)
+
+            json[attr_name] = value if value
+          end
+        end
+
+        # Public: задает аттрибуты на основе хеша
+        def assign(options = {})
+          options.each do |key, value|
+            unless self.class.json_attr_names.include?(key.to_s)
+              raise "Undefined attribute #{key}, allowed attributes are #{self.class.json_attr_names}"
+            end
+
+            send("#{key}=", value)
+          end
+        end
+
+        def eql?(other)
+          slug == other.to_s
+        end
+        alias_method :==, :eql?
+
+        def to_s
+          slug.to_s
+        end
+
+        def hash
+          slug.hash
+        end
+
+        def inspect
+          "<#{self.class} slug = #{slug}>"
+        end
+
+        # Public: находит зависимости для текущего документа
+        #
+        # Arguments:
+        #  reverse - флаг для отпеределения какой тип зависимостей нужно вернуть
+        #    возможные значения
+        #      - false (default) - документы, от которых зависит текущий документ (AKA зависимости self)
+        #      - true - документы, которые зависят от текущего (AKA потребители self)
+        #
+        # Returns Array of Pairs - [[doc1, doc2], [doc1, doc2]]
+        def dependencies(reverse: false)
+          @dependencies ||= Hash.new do |hash, key|
+            hash[key] = Storage::DependencyGraph.instance.dependencies(
+              self,
+              reverse: key
+            )
+          end
+
+          @dependencies[reverse]
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/storage/dependency_graph.rb

@@ -0,0 +1,96 @@
+require 'singleton'
+
+module Apress
+  module Documentation
+    module Storage
+      # Private: Основное хранилище всех зависимостей между документами
+      # Инкапсулирует орентированный граф, вершины которого документы (Document или SwaggerDocument)
+      class DependencyGraph
+        include Singleton
+
+        # Public: добавление документа
+        #
+        # Arguments:
+        #  document - (String or Document) - документ или его слаг(если документ еще не был создан)
+        #
+        # Note:
+        #   Данный метод позволяет ""лениво"" создавать документы в графе,
+        #   подменяя слаг документа, вставленного в граф до создания самого документа, на сам документ
+        # Returns nothing
+        def add_document(document)
+          if graph.has_vertex?(document)
+            graph.replace_vertex(document, document)
+          else
+            graph.add_vertex(document)
+          end
+        end
+
+        # Public: добавление связи между документами, создает ребро в графе, если оно не было создано
+        #
+        # Arguments:
+        #  document_from - (Document) - документ от который зависит
+        #  document_to - (String or Document) - документ или его слаг(если документ еще не был создан)
+        #
+        # Returns nothing
+        def add_dependency(document_from, document_to)
+          graph.add_edge(document_from, document_to) unless graph.has_edge?(document_from, document_to)
+        end
+
+        # Public: находит все зависимости для заданного документа
+        #
+        # Arguments:
+        #  contract - (Document) - документ для которого определяем зависимости
+        #  reverse - (boolean) - флаг, различает тип определяемых зависимостей
+        #    возможные значения
+        #      - false (default) - документы, от которых зависит текущий документ (AKA зависимости contract)
+        #      - true - документы, которые зависят от текущего (AKA потребители contract)
+        #
+        # Returns Array of Pairs - [[doc_from, doc_to], [doc_from_other, doc_to_other]]
+        def dependencies(contract, reverse:)
+          dep = []
+
+          condition =
+            if reverse
+              lambda { |doc, _, to| doc == to }
+            else
+              lambda { |doc, from, _| doc == from }
+            end
+
+          graph.each_edge do |from, to|
+            next unless condition.call(contract, from, to)
+
+            dep << (reverse ? [to, from] : [from, to])
+          end
+
+          dep
+        end
+
+        # Public: валидирует зависимости
+        #
+        # Throws RuntimeError если найдена вершина неверного типа
+        #
+        # Returns nothing
+        def validate!
+          graph.each_vertex do |v|
+            unless v.is_a?(Apress::Documentation::Storage::BaseStorage)
+              raise "Несуществующий документ - #{v}, объявлен в - #{dependencies(v, reverse: true).map(&:last)}"
+            end
+          end
+        end
+
+        # Public: очищает все текущие зависисмости
+        #
+        # Returns nothing
+        def reset!
+          @graph = RGL::DirectedAdjacencyGraph.new
+        end
+
+        private
+
+        def graph
+          @graph ||= RGL::DirectedAdjacencyGraph.new
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/storage/document.rb

@@ -0,0 +1,52 @@
+require_relative 'base_storage'
+require_relative '../dsl/document'
+
+module Apress
+  module Documentation
+    module Storage
+      # Protected
+      #
+      # Внутренний класс системы документации
+      # Описывает отдельный документ
+      class Document < BaseStorage
+        include Apress::Documentation::Dsl::Document
+        # Public: Заголовок документа
+        json_attr :title
+        # Public: Описание документа
+        json_attr :description
+        # Public: Бизнесс описание - заполняется менаджером
+        json_attr :business_desc
+        # Public: Наличие тестов, ссылка на задачу с тестами
+        json_attr :tests
+        # Public: Публичность описываемого функционала - (Защищенный, Публичный)
+        json_attr :publicity
+
+        def initialize(slug)
+          @slug = slug
+        end
+
+        # Public: проверка, необходимо ли для данного документа отображать SwaggerUI
+        def swagger?
+          !swagger_documents.empty?
+        end
+
+        # Public: Хранит дочерние документы
+        def documents
+          @documents ||= {}
+        end
+
+        # Public: Хранит объекты SwaggerDocument для отображения на одной старнице через SwaggerUI
+        def swagger_documents
+          @swagger_documents ||= {}
+        end
+
+        # Public: находит документ верхнего уровня - модуль
+        #
+        # Returns Document
+        def current_module
+          Apress::Documentation::Storage::Modules.instance[slug.to_s.split('/').first]
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/storage/modules.rb

@@ -0,0 +1,83 @@
+require 'singleton'
+require_relative '../dsl/modules'
+
+module Apress
+  module Documentation
+    module Storage
+      # Protected
+      #
+      # Класс хранения документов верхнего уровня (модулей)
+      class Modules
+        include Apress::Documentation::Dsl::Modules
+        include Singleton
+
+        # Public
+        #
+        # Хеш модулей
+        def data
+          @data ||= {}
+        end
+
+        # Public
+        #
+        # Добавление модуля
+        #
+        # Arguments
+        #   document - Document
+        #
+        # Example usage:
+        #   Apress::Documentation::Modules.instance << document
+        def <<(document)
+          data[document.slug.to_s] = document
+        end
+
+        # Public
+        #
+        # Поиск модуля
+        #
+        # Arguments
+        #   slug - String (или любой совместимый объект) - слаг документа
+        #
+        # Example usage:
+        #   Apress::Documentation::Modules.instance[slug]
+        #
+        # Returns Document
+        def [](slug)
+          data[slug.to_s]
+        end
+
+        # Public
+        #
+        # Получение документа по его URL
+        #
+        # Arguments
+        #   path - String -  строка разделенная '/' (пример "/module/document/some_function")
+        #
+        # Example usage:
+        #   Apress::Documentation.fetch_document('module_name/document/test')
+        def fetch_document(path)
+          keys = path.split('/')
+          doc = data[keys.shift]
+          return unless doc
+
+          keys.each do |key|
+            doc = doc.documents[key] || (doc.respond_to?(:swagger_documents) && doc.swagger_documents[key])
+            break unless doc
+          end
+
+          doc
+        end
+
+        # Public
+        #
+        # Удаление всех документов, используется для тестирования
+        #
+        # Example usage:
+        #  Apress::Documentation.reset!
+        def reset!
+          @data = {}
+        end
+      end
+    end
+  end
+end