Merge pull request #2739 from jgayfer/docs_site

Add docs site shell

Author: tvdeyen

docs_site/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "middleman", "~> 4.2"
+gem "oga", "~> 2.14"
+gem "nokogiri", "~>1.8.1"
+gem "middleman-blog", "~> 4.0"
+gem "middleman-s3_sync"
+gem "redcarpet"

docs_site/README.md

@@ -0,0 +1,26 @@
+Based on [https://github.com/joshukraine/middleman-gulp](https://github.com/joshukraine/middleman-gulp)
+
+Requirements
+------------
+
+* [Middleman 4.x][middleman-docs]
+* [Ruby 2.x][rbenv]
+* [Node 8.x][nvm]
+* [Gulp CLI][gulp-cli]
+
+Usage
+-----
+
+1. Install ruby gems `bundle install`
+
+2. Install npm packages `npm install` 
+
+3. Start the Middleman server. Note that this will also invoke Webpack via the external pipeline.
+
+        $ bundle exec middleman server
+
+4. To build html and assets for production, run
+
+        $ bundle exec middleman build
+        
+5. Set proper `base_url` in config.rb         

docs_site/config.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'helpers/image_helpers'
+
+page "/*.xml", layout: false
+page "/*.json", layout: false
+page "/*.txt", layout: false
+page "/developers/*", layout: 'article'
+page "/contributing*", layout: 'article'
+page "/acknowledgements*", layout: 'article'
+page "/404.html", directory_index: false
+
+set :css_dir, "assets/stylesheets"
+set :images_dir, "assets/images"
+set :js_dir, "assets/javascripts"
+set :base_url, build? ? "https://solidus.io" : "http://localhost:4567"
+
+activate :directory_indexes
+page "/developers/*", :directory_index => false
+page "/contributing*", :directory_index => false
+page "/acknowledgements*", :directory_index => false
+
+helpers do
+  def kabob_case(title)
+    title.gsub(' ', '-').downcase
+  end
+
+  def category_matches_page?(href)
+    current_page.url.include?(href.sub(/\/[^\/]*$/, ''))
+  end
+
+  def menu_item_matches_page?(href)
+    current_page.url.chomp('/').eql?(href)
+  end
+
+  def retrieve_page_header(page = current_page)
+    markup = String(page.render( {layout: false} ))
+    markup[/>(.*?)<\/h1>/, 1]
+  end
+
+  def discover_title(page = current_page)
+    page_title = current_page.data.title || retrieve_page_header(page)
+    category = page.path[/\/(.*?)\/.*\.html/, 1]&.gsub('-', ' ')&.capitalize
+    [category, page_title, "Solidus Developers Guide"].compact.join(" | ")
+  end
+end
+
+class CustomMarkdownRenderer < Redcarpet::Render::HTML
+  include ImageHelpers
+
+  def block_code(code, language)
+    path = code.lines.first[/^#\s(\S*)$/, 1]
+    code = code.lines[1..-1].join if path
+    code = code.gsub('<', '&lt').gsub('>', '&gt')
+    template = File.read('source/partials/_code_block.erb')
+    ERB.new(template).result(binding)
+  end
+
+  def table(header, body)
+    header_labels = header.scan(/<th>([\s\S]*?)<\/th>/).flatten
+    table_rows = parse_table(body)
+    template = File.read('source/partials/_table.erb')
+    ERB.new(template).result(binding)
+  end
+
+  def header(text, header_level)
+    "<h%s id=\"%s\" class=\"offset\">%s</h%s>" % [header_level, text.parameterize, text, header_level]
+  end
+
+  def link(link, title, content)
+    template = File.read('source/partials/_anchor.erb')
+    ERB.new(template).result(binding)
+  end
+
+  private
+
+  # This function takes an HTML string and parses it into a nested list
+  # The outer list represents table rows, while the inner lists represent the table data itself
+  def parse_table(table_body)
+    [].tap do |table_rows|
+      table_body.scan(/<tr>([\s\S]*?)<\/tr>/).flatten.each do |tr_inner_markup|
+        tds = []
+        tr_inner_markup.scan(/<td>([\s\S]*?)<\/td>/).flatten.each do |td_inner_markup|
+          tds << td_inner_markup
+        end
+        table_rows << tds
+      end
+    end
+  end
+end
+
+set :markdown_engine, :redcarpet
+
+set :markdown,
+  :tables => true,
+  :autolink => true,
+  :fenced_code_blocks => true,
+  :footnotes => true,
+  :smartypants => true,
+  :with_toc_data => true,
+  :renderer => CustomMarkdownRenderer
+
+activate :external_pipeline,
+         name: :webpack,
+         command: build? ?  "npm run production" : "npm run development",
+         source: ".tmp",
+         latency: 1
+
+activate :s3_sync do |s3_sync|
+  s3_sync.bucket = ENV["AWS_BUCKET"]
+  s3_sync.region = ENV["AWS_REGION"]
+  s3_sync.aws_access_key_id = ENV["AWS_ACCESS"]
+  s3_sync.aws_secret_access_key = ENV["AWS_SECRET"]
+end
+
+default_caching_policy max_age: (60 * 60 * 24 * 365)
+caching_policy "text/html", max_age: 0, must_revalidate: true
+caching_policy "application/xml", max_age: 0, must_revalidate: true
+
+configure :build do
+  activate :asset_hash
+end
+
+set(:port, 4568)

docs_site/data/nav_tree.yml

@@ -0,0 +1,187 @@
+top:
+  - title: "Getting started"
+    dropdown:
+      - title: "First-time installation"
+        href: "/developers/getting-started/first-time-installation.html"
+      - title: "Installation options"
+        href: "/developers/getting-started/installation-options.html"
+      - title: "Develop Solidus"
+        href: "/developers/getting-started/develop-solidus.html"
+      - title: "Forking Solidus"
+        href: "/developers/getting-started/forking-solidus.html"
+main:
+  - title: "Adjustments"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/adjustments/overview.html"
+  - title: "Assets"
+    dropdown:
+      - title: "Asset management"
+        href: "/developers/assets/asset-management.html"
+      - title: "Override Solidus assets"
+        href: "/developers/assets/override-solidus-assets.html"
+  - title: "Calculators"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/calculators/overview.html"
+      - title: "Promotion calculators"
+        href: "/developers/calculators/promotion-calculators.html"
+      - title: "Shipping calculators"
+        href: "/developers/calculators/shipping-calculators.html"
+      - title: "Tax calculator"
+        href: "/developers/calculators/tax-calculator.html"
+  - title: "Extensions"
+    dropdown:
+      - title: "Decorators"
+        href: "/developers/extensions/decorators.html"
+      - title: "Installing extensions"
+        href: "/developers/extensions/installing-extensions.html"
+      - title: "Testing extensions"
+        href: "/developers/extensions/testing-extensions.html"
+  - title: "Inventory"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/inventory/overview.html"
+      - title: "Inventory units"
+        href: "/developers/inventory/inventory-units.html"
+      - title: "Stock items"
+        href: "/developers/inventory/stock-items.html"
+      - title: "Stock movements"
+        href: "/developers/inventory/stock-movements.html"
+  - title: "Locations"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/locations/overview.html"
+      - title: "Countries and states"
+        href: "/developers/locations/countries-and-states.html"
+      - title: "Zones"
+        href: "/developers/locations/zones.html"
+  - title: "Orders"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/orders/overview.html"
+      - title: "Display total methods"
+        href: "/developers/orders/display-total-methods.html"
+      - title: "Order state machine"
+        href: "/developers/orders/order-state-machine.html"
+      - title: "Payment states"
+        href: "/developers/orders/payment-states.html"
+      - title: "Update orders"
+        href: "/developers/orders/update-orders.html"
+  - title: "Payments"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/payments/overview.html"
+      - title: "Payment methods"
+        href: "/developers/payments/payment-methods.html"
+      - title: "Payment processing"
+        href: "/developers/payments/payment-processing.html"
+      - title: "Payment service providers"
+        href: "/developers/payments/payment-service-providers.html"
+      - title: "Payment sources"
+        href: "/developers/payments/payment-sources.html"
+      - title: "Payments"
+        href: "/developers/payments/payments.html"
+      - title: "Refunds"
+        href: "/developers/payments/refunds.html"
+  - title: "Preferences"
+    dropdown:
+      - title: "Add model preferences"
+        href: "/developers/preferences/add-model-preferences.html"
+      - title: "App configuration"
+        href: "/developers/preferences/app-configuration.html"
+      - title: "Class extension points"
+        href: "/developers/preferences/class-extension-points.html"
+  - title: "Products and variants"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/products-and-variants/overview.html"
+      - title: "Multi-currency support"
+        href: "/developers/products-and-variants/multi-currency-support.html"
+      - title: "Product images"
+        href: "/developers/products-and-variants/product-images.html"
+      - title: "Product properties"
+        href: "/developers/products-and-variants/product-properties.html"
+      - title: "Products"
+        href: "/developers/products-and-variants/products.html"
+      - title: "Taxonomies and taxons"
+        href: "/developers/products-and-variants/taxonomies-and-taxons.html"
+      - title: "Variants"
+        href: "/developers/products-and-variants/variants.html"
+  - title: "Promotions"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/promotions/overview.html"
+      - title: "Promotion actions"
+        href: "/developers/promotions/promotion-actions.html"
+      - title: "Promotion handlers"
+        href: "/developers/promotions/promotion-handlers.html"
+      - title: "Promotion rules"
+        href: "/developers/promotions/promotion-rules.html"
+  - title: "Returns"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/returns/overview.html"
+      - title: "Customer returns"
+        href: "/developers/returns/customer-returns.html"
+      - title: "Reimbursement types"
+        href: "/developers/returns/reimbursement-types.html"
+      - title: "Reimbursements"
+        href: "/developers/returns/reimbursements.html"
+      - title: "Return authorizations"
+        href: "/developers/returns/return-authorizations.html"
+      - title: "Return items"
+        href: "/developers/returns/return-items.html"
+  - title: "Shipments"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/shipments/overview.html"
+      - title: "Cartons"
+        href: "/developers/shipments/cartons.html"
+      - title: "Custom shipping calculators"
+        href: "/developers/shipments/custom-shipping-calculators.html"
+      - title: "Shipment setup examples"
+        href: "/developers/shipments/shipment-setup-examples.html"
+      - title: "Shipping method filters"
+        href: "/developers/shipments/shipping-method-filters.html"
+      - title: "Solidus active shipping extensions"
+        href: "/developers/shipments/solidus-active-shipping-extension.html"
+      - title: "Split shipments"
+        href: "/developers/shipments/split-shipments.html"
+      - title: "User interface for shipments"
+        href: "/developers/shipments/user-interface-for-shipments.html"
+  - title: "Taxation"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/taxation/overview.html"
+      - title: "Custom tax calculators"
+        href: "/developers/taxation/custom-tax-calculators.html"
+      - title: "Displaying prices"
+        href: "/developers/taxation/displaying-prices.html"
+      - title: "Example tax setups"
+        href: "/developers/taxation/example-tax-setups.html"
+      - title: "Value-added tax (VAT)"
+        href: "/developers/taxation/value-added-tax.html"
+  - title: "Upgrades"
+    dropdown:
+      - title: "Overview"
+        href: "/developers/upgrades/overview.html"
+      - title: "Migrate from Spree"
+        href: "/developers/upgrades/migrate-from-spree.html"
+      - title: "Versioning guidelines"
+        href: "/developers/upgrades/versioning-guidelines.html"
+  - title: "Users"
+    dropdown:
+      - title: "Addresses"
+        href: "/developers/users/addresses.html"
+      - title: "Custom authentication"
+        href: "/developers/users/custom-authentication.html"
+  - title: "Views"
+    dropdown:
+      - title: "Custom frontend"
+        href: "/developers/views/custom-frontend.html"
+      - title: "Override views"
+        href: "/developers/views/override-views.html"
+bottom:
+  - title: "Contributing"
+    href: "/contributing.html"

docs_site/helpers/custom_helpers.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CustomHelpers
+  def full_title(site_title, page_title = nil)
+    page_title ||= ""
+    if page_title.empty?
+      site_title
+    else
+      page_title + " | " + site_title
+    end
+  end
+
+  def smart_robots(path, env)
+    # Add paths (like "thank you" pages) that search engines should not index.
+    # Multiple paths look like this:
+    # /first_path|another_path|yet_another/
+    if !!(path =~ /thanks/) || env != "production"
+      "noindex, nofollow"
+    else
+      "index, follow"
+    end
+  end
+
+  # return "active" if current page = path. used for navigation classes
+  def nav_active(path)
+    (current_page.path.start_with? path) ? "active" : ""
+  end
+
+  # return "active" if current page is not in paths array. used for navigation classes
+  def nav_inactive(paths)
+    cls = "no-active"
+    paths.each do |path|
+      if current_page.path.start_with?(path)
+        cls = ""
+      end
+    end
+    cls
+  end
+end