Merge branch 'pangolin-drafts' into MQE-336

Author: dshevtsov

README.md

@@ -33,7 +33,7 @@ Visit http://localhost:4000 in your favorite browser!
 
 ## <a name="build-using-docker"> Build using Docker
 
-[This Docker container](https://github.com/jcalcaben/docker-for-devdocs) contains everything necessary to run Jekyll3 for working with Magento DevDocs.
+[This Docker container](https://github.com/magento-devdocs/docker-for-devdocs) contains everything necessary to run Jekyll3 for working with Magento DevDocs.
 
 ## <a name="build-using-vagrant"> Build using Vagrant
 

Rakefile

@@ -1,7 +1,7 @@
 require 'html-proofer'
-
-# Write console output (stderr only) to a file. Use this if you need to also capture stdout: https://stackoverflow.com/a/2480439
-$stderr.reopen("tmp/bad-links.txt", "w")
+require 'kramdown'
+require 'find'
+require 'launchy'
 
 ##############
 #   Build    #
@@ -19,15 +19,20 @@ end
 #   Validate   #
 ################
 
-# Run htmlproofer to check for broken links
+# Run htmlproofer to check for broken linkss
 
 desc "Validate links"
-task :check_links do
-  # First, generate the devdocs site.
-  Rake::Task['build'].invoke
-  # Then, run the link checker.
+task :check_links => :build do
+
+  # We're expecting link validation errors, but unless we rescue from StandardError, rake will abort and won't run the transform task (https://stackoverflow.com/a/10048406). Wrapping task in a begin-rescue block prevents rake from aborting. Seems to prevent printing an error count though.
+  begin
+
   puts 'Checking links with htmlproofer...'
-  # Link checker parameters:
+
+  # Write console output (stderr only) to a file. Use this if you need to also capture stdout: https://stackoverflow.com/a/2480439
+  $stderr.reopen("tmp/.htmlproofer/bad-links.md", "w")
+
+  # Configure htmlproofer parameters:
   options = {
     log_level: :info,
     only_4xx: true,
@@ -44,4 +49,89 @@ task :check_links do
     cache: { :timeframe => '30d' }
   }
   HTMLProofer.check_directory("./_site", options).run
+
+  # We're expecting link validation errors, but unless we rescue from StandardError, rake will abort and won't run the transform task (https://stackoverflow.com/a/10048406). Wrapping task in a begin-rescue block prevents rake from aborting. Seems to prevent printing an error count though.
+  rescue StandardError => e
+    #lifeboats
+  end
+end
+
+#################
+#   Transform   #
+#################
+
+# Make 'tmp/.htmlproofer/bad-links.md' easier to read by transforming it to HTML and applying some CSS.
+
+# We created this task to help us resolve the initial set of errors on the devdocs site. It shouldn't be necessary after we resolve all outstanding errors because we shouldn't expect a large number of errors after initial clean up.
+
+desc "transform link validation error output to HTML"
+task :transform do
+
+  # Define the output directory.
+  SITE_PATH = './tmp/.htmlproofer'
+
+  # Create the output directory if it doesn't already exist.
+  Dir.mkdir( SITE_PATH ) unless File.exist?( SITE_PATH )
+
+  # Define the Kramdown method to convert markdown to HTML.
+  def markdown( text )
+    Kramdown::Document.new( text ).to_html
+  end
+
+    # Locate the output directory, iterate over markdown files inside it, and convert those files to HTML.
+    Find.find('./tmp/.htmlproofer') do |path|
+    if File.extname(path) == '.md'              # e.g. ./index.md => .md
+      basename = File.basename(path, '.md')     # e.g. ./index.md => index
+      File.open( "#{SITE_PATH}/#{basename}.html", 'w') do |file|
+        file.write markdown( File.read( path ) )
+      end
+    end
+  end
+
+  # Automatically open the HTML report in a browser.
+  uri = './tmp/.htmlproofer/bad-links.html'
+  Launchy.open( uri ) do |exception|
+    puts "Attempted to open #{uri} and failed because #{exception}"
+  end
+
+  # Open the report and append CSS. When I try prepending it using the r+ mode (https://stackoverflow.com/a/3682374), which is where CSS content should go, it trucates part of the top error. This is good enough for now.
+  File.open('./tmp/.htmlproofer/bad-links.html', 'a') { |file| file.write('<link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
+  <style>
+
+  /* Lists
+  –––––––––––––––––––––––––––––––––––––––––––––––––– */
+
+  ul {
+    list-style: disc;
+    font-family: \'Roboto\', sans-serif;
+    color: red; }
+  ol {
+    list-style: decimal inside; }
+  ol, ul {
+    padding-left: 0;
+    margin-top: 0; }
+  ul ul,
+  ul ol,
+  ol ol,
+  ol ul {
+    margin: 1.5rem 0 1.5rem 3rem;
+    font-size: 90%;
+    color: black;}
+  li {
+    margin-bottom: 1rem;
+    font-weight: bold;}
+
+  </style>') }
+
+end
+
+###############
+#   Report   #
+###############
+
+# Generate an HTML report of all link validation errors.
+
+desc "generate link validation html report"
+task :link_report => [:check_links, :transform] do
+  puts "generating link validation HTML report..."
 end

_data/toc/coding-standards.yml

@@ -33,3 +33,4 @@ pages:
 
     - label: Technical guidelines
       url: coding-standards/technical-guidelines/technical-guidelines.html
+      versions: ["2.1","2.2", "2.3"]

_data/toc/module-reference-guide.yml

@@ -3,20 +3,26 @@ pages:
     - label: INTRODUCTION
       url: mrg/intro.html
 
+    - label: Sales
+      url: mrg/ce/Sales.html
+      versions: ["2.0"]
+
     - label: Open Source
       url: mrg/ce/ce-intro.html
+      versions: ["2.1","2.2"]
       children:
 
         - label: Sales
           url: mrg/ce/Sales.html
 
         - label: Signifyd
           url: mrg/ce/Signifyd.html
+          versions: ["2.2"]
 
 
     - label: Commerce
       url: mrg/ee/ee-intro.html
-      versions: ["2.1","2.2", "2.3"]
+      versions: ["2.1","2.2"]
       children:
 
         - label: BundleStaging
@@ -96,7 +102,7 @@ pages:
 
     - label: B2B
       url: mrg/b2b/b2b-intro.html
-      versions: ["2.2", "2.3"]
+      versions: ["2.2"]
       children:
 
         - label: B2b

_data/toc/web-api.yml

@@ -19,6 +19,8 @@ pages:
         - label: Order Processing with REST APIs Tutorial
           class: tutorial
           url: get-started/order-tutorial/order-intro.html
+          versions: ["2.1", "2.2", "2.3"]
+
 
     - label: Use SOAP Services
       url: get-started/soap/soap-web-api-calls.html

_includes/install/sampledata/sample-data-clone.md

@@ -23,7 +23,7 @@ See the following sections:
 ## Clone the sample data repository {#clone-sample-repo}
 This section discusses how to install Magento sample data by cloning the sample data repository. You can clone the sample data repository in any of the following ways:
 
-*   Clone with the <a href="#instgde-prereq-sample-clone-ssh">SSH protocol</a>
+*   Clone with the <a href="#clone-sample-repo-ssh">SSH protocol</a>
 *   Clone with the <a href="#instgde-prereq-compose-clone-https">HTTPS protocol</a>
 
 ### Clone with SSH {#clone-sample-repo-ssh}
@@ -56,11 +56,11 @@ fatal: The remote end hung up unexpectedly</pre>
     </div>
 7.  Change to the `<your Magento sample data clone dir>/dev/tools` directory.
 8.  Enter the following command to create symbolic links between the files you just cloned so sample data works properly:
-        
+
         php -f <sample-data_clone_dir>/dev/tools/build-sample-data.php -- --ce-source="<path_to_your_magento_instance>"
 9.  Wait for the command to complete.
 
-10. See <a href="#instgde-prereq-compose-clone-perms">Set file system permissions and ownership</a>.
+10. See <a href="#samp-data-perms">Set file system permissions and ownership</a>.
 
 ### Clone with HTTPS {#instgde-prereq-compose-clone-https}
 To clone the Magento sample data GitHub repository using the HTTPS protocol:
@@ -78,7 +78,7 @@ To clone the Magento sample data GitHub repository using the HTTPS protocol:
 3.  Enter `git clone` and paste the value you obtained from step 1.
 
     An example follows:
-        
+
         git clone https://github.com/magento/magento2-sample-data.git
 4.  Wait for the repository to clone on your server.
 5.  Change to the `<your Magento sample data clone dir>/dev/tools` directory.
@@ -122,7 +122,7 @@ To set file system permissions and ownership on the sample data repository:
 
         cd <your {{site.data.var.ce}} install dir>/var
         rm -rf cache/* page_cache/* generation/*
- 
+
 <!-- ABBREVIATIONS -->
 
 *[contributing developer]: A developer who contributes code to the Magento 2 CE codebase

_includes/install/trouble/rc_cron.md

@@ -9,7 +9,7 @@ To verify whether or not your crontab is set up:
 2.	See if the following file exists:
 
 		ls -al <your Magento install dir>/var/.setup_cronjob_status
-		
+
 	If the file exists, cron has run successfully in the past. If the file _does not_ exist, either you haven't yet installed Magento or cron isn't running. In either case, continue with the next step.
 3.	Get more detail about cron.
 
@@ -34,15 +34,15 @@ To verify whether or not your crontab is set up:
 	See one of the following sections for a solution to your issue.
 
 ### Solution: crontab not set up
-To verify your cron jobs are set up properly, see [Set up cron jobs]({{page.baseurl}}install-gde/install/post-install-config.html#post-install-cron").
+To verify your cron jobs are set up properly, see [Set up cron jobs]({{page.baseurl}}install-gde/install/post-install-config.html#post-install-cron).
 
 ### Solution: cron running from incorrect PHP binary
 If your cron job uses a PHP binary different from the web server plug-in, PHP settings errors might display. To resolve the issue, set identical PHP settings for both the PHP command line and the PHP web server plug-in.
 
 For more information about PHP settings, see [Required PHP settings]({{page.baseurl}}install-gde/prereq/php-settings.html).
 
 ### Solution: cron running with errors
-Try running each command manually because the command might display helpful error messages. See [Set up cron jobs]({{page.baseurl}}install-gde/install/post-install-config.html#post-install-cron").
+Try running each command manually because the command might display helpful error messages. See [Set up cron jobs]({{page.baseurl}}install-gde/install/post-install-config.html#post-install-cron).
 
 <div class="bs-callout bs-callout-info" id="info">
 	<p>You must run cron at least <em>twice</em> for the job to execute; the first time to queue jobs, the second time to execute the jobs.</p>

_includes/install/trouble/rc_php-version.md

@@ -15,7 +15,7 @@ You might encounter the following issues with the PHP version readiness check:
 
 	<img src="{{ site.baseurl }}common/images/upgr-tshoot-no-cron.png">
 
-	This is a symptom of incorrect cron job setup. For more information, see [Set up cron jobs]({{page.baseurl}}install-gde/install/post-install-config.html#post-install-cron").
+	This is a symptom of incorrect cron job setup. For more information, see [Set up cron jobs]({{page.baseurl}}install-gde/install/post-install-config.html#post-install-cron).
 
 ### PHP version is incorrect
 If the PHP version reported by the readiness check is incorrect, it's the result of a mismatch of PHP versions between the PHP CLI and the web server plug-in. Magento requires you to use *one version* of PHP for both the CLI (which runs cron) and the web server (which runs the Magento Admin, Component Manager, and System Upgrade).
@@ -32,4 +32,4 @@ To resolve the issue, try the following:
 
 	*	[Version 2.0]({{page.baseurl}}install-gde/system-requirements.html)
 	*	[Version 2.1]({{site.gdeurl21}}install-gde/system-requirements.html)
-*	Set the same PHP settings for both the PHP command line and the PHP web server plug-in as discussed in [PHP configuration options]({{page.baseurl}}install-gde/prereq/php-centos.html#instgde-prereq-timezone)
+*	Set the same PHP settings for both the PHP command line and the PHP web server plug-in as discussed in [PHP configuration options]({{page.baseurl}}install-gde/prereq/php-centos.html#instgde-prereq-timezone)

_layouts/tutorial.html

@@ -8,7 +8,7 @@
 
       {% assign parent = page.breadcrumbs[0] %}
       <div class="back-link">
-        <a href="{{ page.baseurl }}{{ parent.url }}">
+        <a href="{{parent.url}}">
           <i class="back-link-arrow"></i>
           <span class="back-link-subtitle">Return to</span>
           <span class="back-link-title">{{ parent.title }}</span>

guides/v2.0/cloud/access-acct/fastly.md

@@ -56,7 +56,7 @@ To create a branch:
 {% include cloud/cli-get-started.md %}
 
 ## Install Fastly in an Integration branch and deploy {#cloud-fastly-setup}
-You should install the Fastly module on your local, pushing the code to Integration and deploying across to your Staging and Production environments. For {{site.data.var.ece}} 2.2, install Fastly module 1.2.32 or later for all updated settings and full VCL snippet uploading support.
+You should install the Fastly module on your local, pushing the code to Integration and deploying across to your Staging and Production environments. For {{site.data.var.ece}} 2.2, install Fastly module 1.2.33 or later for all updated settings and full VCL snippet uploading support.
 
 <div class="bs-callout bs-callout-warning" markdown="1">
 Don't configure the module in your local before building and deploying. You'll configure the module in those environments.
@@ -121,7 +121,7 @@ Configure the following features and enable additional [configuration options](h
 
 <div class="bs-callout bs-callout-info" id="info" markdown="1">
 *	Ignore the link to create a free Fastly account. We'll provide your Fastly credentials (Service ID and API token).
-*	With Fastly version 1.2.0 and later (we recommend 1.2.32 or later), use the **Upload VCL to Fastly** button to upload your default [VCL snippets](#custom-vcl).
+*	With Fastly version 1.2.0 and later (we recommend 1.2.33 or later), use the **Upload VCL to Fastly** button to upload your default [VCL snippets](#custom-vcl).
 </div>
 
 ## Upload Fastly VCL snippets {#upload-vcl-snippets}
@@ -138,7 +138,7 @@ To use snippets, you must upload the Fastly VCL using the Magento Admin as follo
 	![Upload a Magento VCL to Fastly]({{ site.baseurl }}common/images/cloud_upload-vcl-to-fastly.png)
 
 	<div class="bs-callout bs-callout-info" id="info" markdown="1">
-  		If the **Upload VCL to Fastly** button does not display, you should upgrade the Fastly extension to version 1.2.0 or later. We recommend 1.2.32 or later. For details, see [Update extensions]({{ page.baseurl}}cloud/howtos/update-components.html). Fastly's Composer name is `fastly/magento2`.
+  		If the **Upload VCL to Fastly** button does not display, you should upgrade the Fastly extension to version 1.2.0 or later. We recommend 1.2.33 or later. For details, see [Update extensions]({{ page.baseurl}}cloud/howtos/update-components.html). Fastly's Composer name is `fastly/magento2`.
 	</div>
 
 2.	Once the upload completes, the modal automatically closes with a success message.

guides/v2.0/cloud/basic-information/cloud-fastly.md

@@ -32,7 +32,7 @@ Fastly provides the following powerful tools for Magento:
 
 We highly recommend enabling and using Fastly for your caching and CDN. The only situation you may not want to enable is for a headless deployment.
 
-We strongly recommend installing Fastly module 1.2.32 or later.
+We strongly recommend installing Fastly module 1.2.33 or later.
 
 ## Fastly and 503 timeouts {#timeouts}
 When you receive a 503 error from Fastly, it may be due to a lengthy operation or performing bulk actions. Fastly has a default 60 second time out. Any request that takes longer than 60 seconds will return a 503 error.

guides/v2.0/cloud/basic-information/starter-architecture.md

@@ -92,7 +92,7 @@ This software is *not* upgradable but versions for the following software is con
 * [RabbitMQ]({{page.baseurl}}cloud/project/project-conf-files_services-rabbit.html)
 * [Elasticsearch]({{page.baseurl}}cloud/project/project-conf-files_services-elastic.html)
 
-For Staging and Production, you will use Fastly for CDN and caching. We recommend installing Fastly module 1.2.32 or later. For details, see [Fastly in Cloud]({{page.baseurl}}cloud/basic-information/cloud-fastly.html).
+For Staging and Production, you will use Fastly for CDN and caching. We recommend installing Fastly module 1.2.33 or later. For details, see [Fastly in Cloud]({{page.baseurl}}cloud/basic-information/cloud-fastly.html).
 
 For detailed information on supported versions and extensions, see the following information. These files allow you to configure software versions you want to use in your implementation.
 

guides/v2.0/cloud/reference/discover-arch.md

@@ -169,7 +169,7 @@ This software is *not* upgradable but versions for the following software is con
 * [RabbitMQ]({{page.baseurl}}cloud/project/project-conf-files_services-rabbit.html)
 * [Elasticsearch]({{page.baseurl}}cloud/project/project-conf-files_services-elastic.html)
 
-For Staging and Production, you will use Fastly for CDN and caching. We recommend installing Fastly module 1.2.32 or later. For details, see [Fastly in Cloud]({{page.baseurl}}cloud/basic-information/cloud-fastly.html).
+For Staging and Production, you will use Fastly for CDN and caching. We recommend installing Fastly module 1.2.33 or later. For details, see [Fastly in Cloud]({{page.baseurl}}cloud/basic-information/cloud-fastly.html).
 
 For detailed information on supported versions and extensions, see the following information. These files allow you to configure software versions you want to use in your implementation.
 

guides/v2.0/cloud/requirements/cloud-requirements.md

@@ -89,7 +89,7 @@ This software is *not* upgradable but versions for the following software is con
 * [RabbitMQ]({{page.baseurl}}cloud/project/project-conf-files_services-rabbit.html)
 * [Elasticsearch]({{page.baseurl}}cloud/project/project-conf-files_services-elastic.html)
 
-For Staging and Production, you will use Fastly for CDN and caching. We recommend installing Fastly module 1.2.32 or later. For details, see [Fastly in Cloud]({{page.baseurl}}cloud/basic-information/cloud-fastly.html).
+For Staging and Production, you will use Fastly for CDN and caching. We recommend installing Fastly module 1.2.33 or later. For details, see [Fastly in Cloud]({{page.baseurl}}cloud/basic-information/cloud-fastly.html).
 
 For detailed information on supported versions and extensions, see the following information. These files allow you to configure software versions you want to use in your implementation.