Add docs site shell #2739

jgayfer · 2018-05-18T21:00:31Z

This PR contains the shell of a static site built to house the Solidus developers documentation.

A working version of the site can be viewed at: http://jgayfer.s3-website.us-east-1.amazonaws.com/

This site is modelled after the new Solidus marketing site to ensure a consistent user experience across both sites.

This site could also be used for future Solidus docs sites (API and Admin) to further the goal of a unified Solidus experience on the web.

Rationale

Keeping the source for the docs site within the Solidus repository has several advantages:

It allows the docs to be versioned alongside the code. When major changes are introduced in Solidus, it is clear where and how the docs should also be changed.
Having the docs stay within the Solidus repository ensures that they will be evaluated (by the community and the core developer team) at the same high standard that Solidus code contributions are.
There's no risk in adding the docs site to the main Solidus repository. The docs are self-contained and don't affect the code base. And, for the forseeable future, they don't significantly increase the size of git clones of Solidus.

We can decide to move the docs to another repository in the future. But first, we would need to create a plan to make sure the docs aren't treated as a second-class citizen.

Next steps

Note that this PR is a shell for the docs site:

In a later PR, we would need to move the docs to docs_site/source/developers directory.
We would need to change each article extension from .md to .html.md, as this is the format Middleman requires.
We would also need to go through each article and change each relative link from .md to .html.
Regarding deployment, this site is setup so that it can easily be deployed to an AWS S3 bucket using the middleman-s3_sync gem.

houndci-bot · 2018-05-18T21:00:41Z

docs_site/helpers/image_helpers.rb

+      )
+    end
+  end
+end


Layout/TrailingBlankLines: Final newline missing.

houndci-bot · 2018-05-18T21:00:41Z

docs_site/helpers/image_helpers.rb

+      file = File.open(asset, 'r') { |f| f.read }
+      # we pass svg-targeting css classes through here, ex. .svg-color--blue. The class targets fill, stroke, poly, circle, etc.
+      css_class = options[:class]
+      aspect_ratio = options[:preserveAspectRatio]


Lint/UselessAssignment: Useless assignment to variable - aspect_ratio.

houndci-bot · 2018-05-18T21:00:42Z

docs_site/helpers/image_helpers.rb

+  def inline_svg(filename, options = {})
+    asset = "source/assets/images/#{filename}"
+
+    if File.exists?(asset)


Lint/DeprecatedClassMethods: File.exists? is deprecated in favor of File.exist?.

houndci-bot · 2018-05-18T21:00:42Z

docs_site/helpers/image_helpers.rb

@@ -0,0 +1,51 @@
+# Middleman - Inline SVG Helper


Style/FrozenStringLiteralComment: Missing magic comment # frozen_string_literal: true.

houndci-bot · 2018-05-18T21:00:42Z

docs_site/helpers/custom_helpers.rb

+        cls = ""
+      end
+    end
+    return cls


Style/RedundantReturn: Redundant return detected.

houndci-bot · 2018-05-18T21:00:42Z

docs_site/helpers/custom_helpers.rb

+  def nav_inactive(paths)
+    cls = "no-active"
+    paths.each do |path|
+      if(current_page.path.start_with? path)


Layout/SpaceAroundKeyword: Space after keyword if is missing.

houndci-bot · 2018-05-18T21:00:42Z

docs_site/helpers/custom_helpers.rb

@@ -0,0 +1,37 @@
+module CustomHelpers
+  def full_title(page_title=nil, site_title)


Style/OptionalArguments: Optional arguments should appear at the end of the argument list.
Layout/SpaceAroundEqualsInParameterDefault: Surrounding space missing in default value assignment.

houndci-bot · 2018-05-18T21:00:42Z

docs_site/helpers/custom_helpers.rb

@@ -0,0 +1,37 @@
+module CustomHelpers


Style/FrozenStringLiteralComment: Missing magic comment # frozen_string_literal: true.

houndci-bot · 2018-05-18T21:00:42Z

docs_site/config.rb

+
+  def discover_title(page = current_page)
+    page_title = current_page.data.title || retrieve_page_header(page)
+    category = page.path[/\/(.*?)\/.*\.html/, 1]&.gsub('-', ' ')&.capitalize


Lint/Syntax: unexpected token error

houndci-bot · 2018-05-18T21:00:43Z

docs_site/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"


Style/FrozenStringLiteralComment: Missing magic comment # frozen_string_literal: true.

houndci-bot · 2018-05-18T21:23:37Z

docs_site/helpers/custom_helpers.rb

+  def nav_inactive(paths)
+    cls = "no-active"
+    paths.each do |path|
+      if (current_page.path.start_with? path)


Style/ParenthesesAroundCondition: Don't use parentheses around the condition of an if.

houndci-bot · 2018-05-18T21:23:37Z

docs_site/helpers/custom_helpers.rb

+# frozen_string_literal: true
+
+module CustomHelpers
+  def full_title(site_title, page_title=nil)


Layout/SpaceAroundEqualsInParameterDefault: Surrounding space missing in default value assignment.

kennyadsl · 2018-05-23T15:34:37Z

docs_site/source/topic.html.erb

@@ -0,0 +1,111 @@
+---
+title: Home


is this file needed?

@kennyadsl No, it's not. It was just a template/example of the styles we are using. I'll remove it!

kennyadsl

I didn't see all the files but at the moment I agree we shouldn't move guides files to another repository. Also, the guides preview looks great.

tvdeyen · 2018-05-24T08:38:11Z

Thanks

houndci-bot reviewed May 18, 2018

View reviewed changes

This was referenced May 18, 2018

Move guides to new docs_site jgayfer/solidus#4

Closed

Move guides to new docs site #2740

Merged

jgayfer force-pushed the docs_site branch from 75c2afd to 73a198c Compare May 18, 2018 21:23

houndci-bot reviewed May 18, 2018

View reviewed changes

jgayfer force-pushed the docs_site branch 2 times, most recently from 9049063 to ee8ebcf Compare May 18, 2018 22:16

kennyadsl reviewed May 23, 2018

View reviewed changes

cbrunsdon approved these changes May 23, 2018

View reviewed changes

Add docs site shell

fc8642e

jgayfer force-pushed the docs_site branch from ee8ebcf to fc8642e Compare May 23, 2018 16:24

kennyadsl approved these changes May 23, 2018

View reviewed changes

tvdeyen merged commit 146c69d into solidusio:master May 24, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs site shell #2739

Add docs site shell #2739

jgayfer commented May 18, 2018 •

edited

Loading

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

houndci-bot May 18, 2018

kennyadsl May 23, 2018

jgayfer May 23, 2018

kennyadsl left a comment

tvdeyen commented May 24, 2018

		@@ -0,0 +1,37 @@
		module CustomHelpers
		def full_title(page_title=nil, site_title)

Add docs site shell #2739

Add docs site shell #2739

Conversation

jgayfer commented May 18, 2018 • edited Loading

Rationale

Next steps

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennyadsl left a comment

Choose a reason for hiding this comment

tvdeyen commented May 24, 2018

jgayfer commented May 18, 2018 •

edited

Loading