apress-documentation 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b3884b3865d68ccbb735759200cfc3833e7747c5
+  data.tar.gz: b03241bacd2cd463a790e214d689cebdfc4b2044
+SHA512:
+  metadata.gz: fa018cf839ed6b3d33d78af959ac566b12804560d46f61a2f08cec83477599d1f41def643de73b3a025ff28150bdef6b06567dfbb070ef54a53f78cf4449668a
+  data.tar.gz: 296e6b6572a6325fb1ff9b7650225c69d86cda31d2de703721084f5527b78d2883f44dae2a7cc36ff9cbcb6c49455577373077b4029f6db70f31ef7973c89a20

data/.drone.yml

@@ -0,0 +1,28 @@
+build:
+  test:
+    image: abakpress/dind-testing
+    pull: true
+    privileged: true
+    volumes:
+      - /home/data/drone/images:/images
+      - /home/data/drone/gems:/bundle
+    environment:
+      - COMPOSE_FILE_EXT=drone
+      - RUBY_IMAGE_TAG=2.2-latest
+    commands:
+      - wrapdocker docker -v
+
+      - fetch-images --image abakpress/ruby-app:$RUBY_IMAGE_TAG
+      - dip provision
+      - dip rspec
+
+  release:
+    image: abakpress/gem-publication
+    pull: true
+    when:
+      event: push
+      branch: master
+    volumes:
+      - /home/data/drone/rubygems:/root/.gem
+    commands:
+      - release-gem --public

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/Gemfile.lock
+/coverage/
+/doc/
+/spec/reports/
+/tmp/
+/gemfiles/
+
+# rspec failure tracking
+.rspec_status

data/Appraisals

@@ -0,0 +1,30 @@
+appraise 'rails3.2' do
+  gem 'rails', '>= 3.2', '< 4.0'
+end
+
+appraise 'rails4.0' do
+  gem 'rails', '>= 4.0', '< 4.1'
+end
+
+appraise 'rails4.1' do
+  gem 'rails', '>= 4.1', '< 4.2'
+end
+
+appraise 'rails4.2' do
+  gem 'rails', '>= 4.2', '< 5.0'
+end
+
+appraise 'rails5.0' do
+  gem 'rails', '>= 5.0', '< 5.1'
+  gem 'rails-controller-testing'
+end
+
+appraise 'rails5.1' do
+  gem 'rails', '~> 5.1.0'
+  gem 'rails-controller-testing'
+end
+
+appraise 'rails5.2' do
+  gem 'rails', '~> 5.2.0'
+  gem 'rails-controller-testing'
+end

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# v0.4.0
+
+* 2018-08-22 [2d3b37b](../../commit/2d3b37b) - __(Artem Napolskih)__ chore: Add automatic publication 
+* 2018-08-21 [c419339](../../commit/c419339) - __(Artem Napolskih)__ fix: removes dependence on abak domain system 
+* 2018-08-21 [dddd8ea](../../commit/dddd8ea) - __(Artem Napolskih)__ feature: rails 5.x support added 
+
+# v0.3.0
+
+* 2018-06-06 [386ff0e](../../commit/386ff0e) - __(Maxim Tretyakov)__ feat: route scope option 
+https://jira.railsc.ru/browse/ORDERS-1786
+
+# v0.2.1
+
+* 2017-09-27 [beec36c](../../commit/beec36c) - __(Denis Korobicyn)__ fix: proper cache key 
+
+# v0.2.0
+
+* 2017-07-31 [ad4e903](../../commit/ad4e903) - __(Denis Korobicyn)__ fix: dependencies for swagger documents 
+https://jira.railsc.ru/browse/PC4-19812
+
+* 2017-05-19 [6b3e186](../../commit/6b3e186) - __(Denis Korobicyn)__ feature: modules connections 
+https://jira.railsc.ru/browse/PC4-19783
+
+* 2017-05-12 [9064dc6](../../commit/9064dc6) - __(Denis Korobicyn)__ fix: assets compilation 
+https://jira.railsc.ru/browse/PC4-19468
+
+* 2017-05-10 [62fe08a](../../commit/62fe08a) - __(Denis Korobicyn)__ chore: add missing load_hook for documents_controller 
+* 2017-05-04 [fd80fa6](../../commit/fd80fa6) - __(Denis Korobicyn)__ chore: add load_docs_for method 
+* 2017-05-03 [87005d6](../../commit/87005d6) - __(Denis Korobicyn)__ fix: repo url in gemspec and repo name in readme 
+
+# v0.1.0
+
+* 2017-04-21 [3c66be9](../../commit/3c66be9) - __(Denis Korobicyn)__ Initial commit 
+* 2017-04-21 [db97835](../../commit/db97835) - __(Mamedaliev Kirill)__ Initial commit 

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in apress-documenation.gemspec
+gemspec

data/README.md

@@ -0,0 +1,101 @@
+# Apress::Documentation
+
+
+## Установка
+
+```ruby
+gem 'apress-documentation'
+```
+
+## Использвание
+
+Описание любого компонена задается с помощью вызова метода build на главном модуле `Apress::Documentation` и передаче ему блока. Например,
+```
+Apress::Documentation.build(:module_name, title: 'название модуля') do
+  document(:component, title: 'Название компонента') do
+    description 'test'
+  end
+end
+```
+
+в самом блоке могут быть вызваны методы document, name, description, business_desc, consumers, publicity, tests, swagger_bind.
+
+#### Описания методов
+`document`  определеяет весь документ, является частью построения меню (на каждый документ создается ссылка), данный метод можно вызвать друг друге, например:
+```ruby
+Apress::Documentation.build(:module_name, title: 'название модуля') do
+  document(:component, title: 'Название компонента') do
+    description 'test'
+
+    document(:nested_component, title: 'Вложенный документ') do
+      description 'test here'
+      publicity 'Закрытый'
+    end
+  end
+end
+```
+
+также `document` можно вызывать без блока, если нет неообходимости:
+```ruby
+Apress::Documentation.build(:module_name, title: 'название модуля') do
+  document(:component, title: 'Простой компонент соящий упоминания')
+end
+```
+
+`title` - имя компонента.
+
+`description` - описание компонента.
+
+`business_desc` - бизнес-описание компонента, заполняется менеджером.
+
+`consumers` - перечесление модулей-потребителей.
+
+`tests` - есть ли тесты на компонент, когда были написаны, в рамках какой задачи.
+
+`publicity` - публичность компонента, возможность использования его в других местах, рекомендованные значения -
+"Защищеный", "Публичный".
+
+`swagger_bind` реализует возможность дополнить swagger-ui.
+разрешенные методы - business_desc, consumers, tests и publicity.
+Пример использования:
+```ruby
+Apress::Documentation.build(:module_name, title: 'название модуля') do
+  document(:http_api, title: 'HTTP API') do
+    # аргумент id HTML блока в который будет ставлена доп. инфа
+    swagger_bind('module_operationID_content') do
+      description 'Это апи нужно для того-то'
+
+      consumers 'Other module'
+
+      # тут обычное swagger описание
+      swagger_path('some/path/here') do
+        operation :get do
+          # важно чтобы operation_id и tags совпадали в аргументе swagger_bind
+          key :operationId, 'operationID'
+          key :tags, ['module']
+
+          ...
+        end
+      end
+    end
+
+    # также аргумент HTML id можно опускать, если operationId и tags заданы
+    swagger_bind do
+      description 'Это апи нужно для того-то'
+
+      consumers 'Other module'
+
+      # тут обычное swagger описание
+      swagger_path('some/path/here') do
+        operation :get do
+          # Автоматически поддянет значения и создат HTML id - module_operationID_content
+          key :operationId, 'operationID'
+          key :tags, ['module']
+
+          ...
+        end
+      end
+    end
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/app/assets/javascripts/package/documentation.js

@@ -0,0 +1,18 @@
+//= require swagger-ui/lib/jquery-1.8.0.min.js
+//= require swagger-ui/lib/jquery.slideto.min.js
+//= require swagger-ui/lib/jquery.wiggle.min.js
+//= require swagger-ui/lib/jquery.ba-bbq.min.js
+//= require swagger-ui/lib/handlebars-2.0.0.js
+//= require swagger-ui/lib/underscore-min.js
+//= require swagger-ui/lib/backbone-min.js
+//= require swagger-ui/lib/jsoneditor.min.js
+//= require swagger-ui/lib/highlight.7.3.pack.js
+//= require swagger-ui/lib/marked.js
+//= require swagger-ui/lib/swagger-oauth.js
+//= require swagger-ui/swagger-ui.js
+//= require swagger_ui.js
+//= require_tree ../templates
+//= require shared/dependency_switcher.js
+//= require swagger_binder.js
+
+DependencySwitcher.switchBind();

data/app/assets/javascripts/shared/dependency_switcher.js

@@ -0,0 +1,10 @@
+var DependencySwitcher = (function(self) {
+  self.switchBind = function() {
+    $('.js-dependency-switch', '.js-dependencies-container').change(function() {
+      $('.js-all-dependencies', '.js-dependencies-container').toggle();
+      $('.js-dependencies', '.js-dependencies-container').toggle();
+    });
+  };
+
+  return self;
+})(DependencySwitcher || {});

data/app/assets/javascripts/swagger_binder.js

@@ -0,0 +1,19 @@
+$(function () {
+  Handlebars.registerHelper('fetch', function (value, def) {
+      return value || def;
+  });
+
+  $(document).on('swaggerBind', function(event) {
+    event.preventDefault();
+
+    if(!app.extensions) {
+      return;
+    }
+
+    for(var ext in app.extensions) {
+      $('#' + ext + '_content').prepend(HandlebarsTemplates['document']({document: app.extensions[ext]}));
+    }
+
+    DependencySwitcher.switchBind();
+  });
+});

data/app/assets/javascripts/swagger_ui.js

@@ -0,0 +1,24 @@
+$(function () {
+  if(app.swagger) {
+    window.swaggerUi = new SwaggerUi({
+      url: app.swagger.docsUrl,
+      dom_id: 'swagger-ui-container',
+      supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
+      onComplete: function() {
+        $('pre code').each(function(i, e) {
+          hljs.highlightBlock(e);
+        });
+
+        $(document).trigger('swaggerBind');
+      },
+      onFailure: function() {
+        console.log('Unable to Load SwaggerUI');
+      },
+      docExpansion: (app.swagger.docsExpansion || 'none'),
+      jsonEditor: true,
+      defaultModelRendering: 'schema',
+      showRequestHeaders: true
+    });
+    window.swaggerUi.load();
+  }
+});

data/app/assets/javascripts/templates/document.hamlbars

@@ -0,0 +1,25 @@
+%h4 Бизнесс описание
+%span
+  {{fetch document.business_desc "Нет данных"}}
+
+%h4 Публичность
+%span
+  {{fetch document.publicity "Нет данных"}}
+
+%h4 Тесты
+%span
+  {{fetch document.tests "Нет данных"}}
+
+%h4 Зависимости
+.js-dependencies-container
+  .switch
+    %input.switch-checkbox.js-dependency-switch{type: "checkbox", id: "doc-switch-{{document.slug}}"}
+    %label.switch-label{for: "doc-switch-{{document.slug}}"}
+      %span.switch-inner
+      %span.switch-switch
+
+  %h5 Зависит от
+  {{{fetch document.depends_on "Нет данных"}}}
+
+  %h5 Используется в
+  {{{fetch document.consumers "Нет данных"}}}

data/app/assets/stylesheets/document/base.scss

@@ -0,0 +1,112 @@
+@import 'variables';
+
+* {
+  -webkit-font-smoothing: antialiased;
+  -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
+  -moz-osx-font-smoothing: grayscale;
+  box-sizing: border-box;
+
+  &:focus,
+  &:active {
+    outline: none;
+  }
+}
+
+body {
+  background-color: $body-bg;
+  color: $text-color;
+  font-family: $font-family;
+  font-size: $font-size;
+  line-height: $line-height;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: $font-family-headings;
+  font-weight: $headings-font-weight;
+  color: $heading-color;
+  line-height: $heading-line-heading;
+  margin: 1.6em 0 .8em;
+}
+
+h1 {
+  font-size: 1.5em;
+  border-bottom: 1px solid lighten($border-accent-color, 1%);
+  padding-bottom: .6em;
+
+  & > a {
+    & > img {
+      vertical-align: middle;
+      position: relative;
+      top: -2px;
+      margin-left: 1px;
+      height: 18px;
+
+      @media(max-width: $screen-sm-max) {
+        display: none;
+      }
+    }
+
+    &:first-child {
+      & > img {
+        margin-left: 15px;
+      }
+    }
+  }
+}
+
+h2 { font-size: 1.3em; }
+h3 { font-size: 1.1em; }
+h4 { font-size: 1em; }
+h5 { font-size: .9em; }
+h6 { font-size: .8em; }
+
+p {
+  margin: 0 0 .8em;
+}
+
+a {
+  color: $link-color;
+
+  &:hover {
+    color: darken($link-color, 10%);
+  }
+
+  &,
+  &:hover {
+    text-decoration: none;
+  }
+
+  &[name] {
+    display: block;
+    padding-top: 15px;
+  }
+}
+
+.content {
+  *:not(a) {
+    & > img:not([class]) {
+      border: 1px solid $border-accent-color;
+      padding: 4px;
+      background-color: #fff;
+      border-radius: 2px;
+      display: block;
+      max-width: 100%;
+      height: auto;
+    }
+  }
+
+  ul:not([class]) {
+    li {
+      padding-bottom: 5px;
+    }
+  }
+}
+
+.hidden {
+  display: none;
+}