Merge pull request platformsh#354 from platformsh/reorg

Refactor documentation structure into a single shallow-outline book

.editorconfig

@@ -10,3 +10,6 @@ indent_style = space
 end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
+
+[Makefile]
+indent_style = tab

.gitignore

@@ -2,3 +2,4 @@ _book/*
 _books/*
 .DS_Store
 .env
+node_modules/*

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "user-widget"]
-    path = node_modules/gitbook-theme-platform/book/user-widget
-    url = [email protected]:accounts/user-widget.git
+[submodule "src/user-widget"]
+	path = src/scripts/user-widget
+	url = [email protected]:accounts/user-widget.git

.platform.app.yaml

@@ -2,7 +2,7 @@
 # in the same project.
 
 # The name of this app. Must be unique within a project.
-name: php
+name: app
 
 # The toolstack used to build the application.
 type: php:7.0
@@ -13,15 +13,14 @@ build:
 web:
     locations:
         "/":
-            root: "_books"
-            passthru: "/index.php"
+            root: "_book"
             index:
                 - "index.html"
             expires: -1
             scripts: true
             allow: false
             rules:
-                \.(css|js|gif|jpe?g|png|ttf|eot|woff2?|otf|html?)$:
+                \.(css|js|gif|jpe?g|png|ttf|eot|woff2?|otf|html|ico|svg?)$:
                     allow: true
                 ^/robots\.txt$:
                     allow: true
@@ -38,4 +37,7 @@ dependencies:
 # The hooks that will be performed when the package is deployed.
 hooks:
     build: |
-      ./build_all
+      gitbook install
+      gitbook build
+      # Gitbook doesn't allow for a custom favicon except through a theme plugin. So Plan B.
+      cp src/images/favicon.ico _book/gitbook/images/favicon.ico

.platform/routes.yaml

@@ -1,10 +1,12 @@
 http://www.{default}/:
-  to: https://{default}/
   type: redirect
-http://{default}/:
   to: https://{default}/
+http://{default}/:
   type: redirect
+  to: https://{default}/
 https://{default}/:
+  type: upstream
+  upstream: app:http
   cache:
     cookies:
     - '*'
@@ -15,5 +17,25 @@ https://{default}/:
     - Accept-Language
   ssi:
     enabled: false
-  type: upstream
-  upstream: php:http
+  redirects:
+    paths:
+      # The following were the most common paths on the old site; redirect to the
+      # corresponding new page. These redirects should be safe to remove in 2017.
+      "/user_guide/reference/paltform-app-yaml.html": { "to": "/configuration/app-containers.html", "code": "301", "prefix": false}
+      "/user_guide/overview/configuring-project-environments.html": { "to": "/administration/web/configure-environment.html", "code": "301", "prefix": false}
+      "/user_guide/using/going-live.html": { "to": "/development/going-live.html", "code": "301", "prefix": false}
+      "/user_guide/using/set-up-local-development.html": { "to": "/development/local.html", "code": "301", "prefix": false}
+      "/user_guide/reference/configuration-files.html": { "to": "/configuration/app-containers.html", "code": "301", "prefix": false}
+      "/user_guide/use-SSH.html": { "to": "/development/ssh.html", "code": "301", "prefix": false}
+      "/user_guide/overview/web-ui/configure-environments.html": { "to": "/administration/web/environments.html", "code": "301", "prefix": false}
+      "/user_guide/overview/web-ui/configure-project.html": { "to": "/administration/web/configure-project.html", "code": "301", "prefix": false}
+      "/user_guide/overview/cli/index.html": { "to": "/overview/cli.html", "code": "301", "prefix": false}
+      "/user_guide/reference/toolstacks/php/index.html": { "to": "/languages/php.html", "code": "301", "prefix": false}
+      "/user_guide/reference/environment-variables.html": { "to": "/development/environment-variables.html", "code": "301", "prefix": false}
+      "/user_guide/using/index.html": { "to": "/administration/users.html", "code": "301", "prefix": false}
+      "/user_guide/overview/technical-requirements.html": { "to": "/overview/tools.html", "code": "301", "prefix": false}
+      "/user_guide/reference/faq/known-issues.html": { "to": "/development/faq.html", "code": "301", "prefix": false}
+      "/drupal_migrate/guides/type/php/drupal/migrate/import-database.html": { "to": "/drupal7/migrating.html", "code": "301", "prefix": false}
+      "/user_guide/reference/toolstacks/php/configure-php.html": { "to": "/languages/php.html", "code": "301", "prefix": false}
+      "/user_guide/overview/services.html": { "to": "/configuration/services.html", "code": "301", "prefix": false}
+

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to the Platform.sh User Documentation
+
+Thank you for helping make our documentation better!
+
+In order to maintain a consistent style and voice throughout our documentation please try to follow these standards and conventions when filing Pull Requests against our documentation.
+
+## Markdown
+
+GitBook (which we use for documentation) uses Markdown as its file format.  
+
+* All files should end in `.md`. They should be all-lower-case and match the title of the page, or in some cases an abbridged version of it.
+* All pages should start with a title, denoted with # (first level header).
+* Subsections within a page are encouraged, and should use ## for a 2nd level and ### for a 3rd level. Do not have more than 3 levels of header.
+* Inline code statements, file names, and keys that would appear in a file should use backticks ``like this``.
+* Longer code samples should be denoted with triple backticks before and after, with no extra whitespace between the backticks and the code block. Always specify the language of the code block.  See the [highlight.js docs](https://highlightjs.org/static/demo/) for available language options.  (`yaml`, `bash`, and `php` are the most common we're likely to see).
+* Always use inline links.
+* Do not hard-wrap prose text.  Set your text editor to soft wrapping.
+* Internal links should be absolute (starting with `/`) and link to a file ending in `.md`, not `.html`. That makes them easier to find when needed to update.
+
+## Content
+
+The goal of Platform.sh's documentation is to help tech-savvy users self-educate on how to use and get the most out of Platform.sh.  Therefore, the reader should be assumed to be familiar with common web development tools and practices (version control, Git, branching, web servers, databases, etc.), but not necessarily with server administration.  When in doubt, favor providing more background information rather than less, and/or link out to existing resources for background.
+
+ The aim of the documentation is less to provide context-less "how" information but to emphasize the underlying "why" behind what needs to be done.  All documentation should strive to help improve the user's mental model of how the system works so that they can self-educate more effectively. That also means that not every tip or trick needs to be included if they're not especially common cases.
+
+ That said, undocumented options should be treated as a bug, unconditionally.
+
+## Structure
+
+* Favor short titles for pages and sections.
+* Titles of pages and sections should use Sentence case.  That is, capitalize the first word and proper nouns only.
+* Never have a page in the outline that is more than 2 levels deep. That is, never have a sub-sub item.  That ensures all pages are at most 2 clicks away from any other page.
+* Each page should cover one topic, but should completely cover that topic. Do not break topics across multiple pages needlessly.
+* The use of asides should be sparing.  If used, they must begin with a `**bolded**` header of "node" or "warning", as appropriate. Most text simply belongs as part of the prose, however.
+
+## Language usage
+
+* All documentation should be written in American English, using American English spelling.
+* Always use the [Oxford Comma](https://en.wikipedia.org/wiki/Serial_comma).
+* The name of the company is always written as "Platform.sh", not simply "Platform". It should not be linked anywhere. 
+* "We" should, if used, always refer to Platform.sh the company.  However, avoid its use where feasible.
+* The reader is assumed to be a developer, and should be addressed as "you".  E.g., "Once you add this file to your repository...".
+* Avoid the use of gender-specific pronouns (he/she, his/her).  The "singular they" (they/their) should be used when it is necessary to refer to a person in the 3rd person.
+
+## Process
+
+* Favor many small PRs over larger ones.
+* Never push directly to the master branch.
+* Never merge your own PR, unless not doing so would result in customer data loss.

Makefile

@@ -0,0 +1,10 @@
+# This file contains build steps that need to be run offline, not as part of
+# The Platform.sh build process.
+
+all: graphs
+
+graphs: build-pipeline
+
+build-pipeline:
+	dot -Tsvg -osrc/images/build-pipeline.svg src/images/build-pipeline.dot
+