Merge branch 'docs-route-maps' into 'master'

Docs route maps

Closes #53178

See merge request gitlab-org/gitlab-ce!24488

6 files changed, 99 insertions, 76 deletions

diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 010c579b83e..b9b5ceab7fb 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -416,81 +416,15 @@ and/or `production`) you can see this information in the merge request itself.
 
 ### Go directly from source files to public pages on the environment
 
-> Introduced in GitLab 8.17. In GitLab 11.5 the file links
-are surfaced to the merge request widget.
-
-You can specify a Route Map to get GitLab to show **View on ...**
-buttons to go directly from a file to that file's representation on the
-[deployed website via Review Apps](review_apps/index.md).
-
-To get this to work, you need to tell GitLab how the paths of files in your repository map to paths of pages on your website, using a Route Map.
-
-A Route Map is a file inside the repository at `.gitlab/route-map.yml`, which contains a YAML array that maps `source` paths (in the repository) to `public` paths (on the website).
-Below is an example of a route map for [Middleman](https://middlemanapp.com) static websites
-like <https://gitlab.com/gitlab-com/www-gitlab-com>:
-
-```yaml
-# Team data
-- source: 'data/team.yml' # data/team.yml
-  public: 'team/' # team/
-
-# Blogposts
-- source: /source\/posts\/([0-9]{4})-([0-9]{2})-([0-9]{2})-(.+?)\..*/ # source/posts/2017-01-30-around-the-world-in-6-releases.html.md.erb
-  public: '\1/\2/\3/\4/' # 2017/01/30/around-the-world-in-6-releases/
-
-# HTML files
-- source: /source\/(.+?\.html).*/ # source/index.html.haml
-  public: '\1' # index.html
-
-# Other files
-- source: /source\/(.*)/ # source/images/blogimages/around-the-world-in-6-releases-cover.png
-  public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png
-```
-
-Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, we have a hash map with two keys:
-
-- `source`
-    - a string, starting and ending with `'`, for an exact match
-    - a regular expression, starting and ending with `/`, for a pattern match
-      - The regular expression needs to match the entire source path - `^` and `$` anchors are implied.
-      - Can include capture groups denoted by `()` that can be referred to in the `public` path.
-      - Slashes (`/`) can, but don't have to, be escaped as `\/`.
-      - Literal periods (`.`) should be escaped as `\.`.
-- `public`
-    - a string, starting and ending with `'`.
-      - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`.
-
-The public path for a source path is determined by finding the first `source` expression that matches it, and returning the corresponding `public` path, replacing the `\N` expressions with the values of the `()` capture groups if appropriate.
-
-In the example above, the fact that mappings are evaluated in order of their definition is used to ensure that `source/index.html.haml` will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`, and will result in a public path of `index.html`, instead of `index.html.haml`.
-
----
-
-Once you have the route mapping set up, it will be exposed in a few places:
-
-- In the merge request widget. The **View app** button will take you to the
-  environment URL you have set up in `.gitlab-ci.yml`. The dropdown will render
-  the first 5 matched items from the route map, but you can filter them if more
-  than 5 are available.
-
-    ![View app file list in merge request widget](img/view_on_mr_widget.png)
-
-- In the diff for a merge request, comparison, or commit.
-
-    !["View on env" button in merge request diff](img/view_on_env_mr.png)
-
-- In the blob file view.
-
-    !["View on env" button in file view](img/view_on_env_blob.png) |
-
----
-
-We now have a full development cycle, where our app is tested, built, deployed
-as a Review app, deployed to a staging server once the merge request is merged,
-and finally manually deployed to the production server. What we just described
-is a single workflow, but imagine tens of developers working on a project
-at the same time. They each push to their branches, and dynamic environments are
-created all the time. In that case, we probably need to do some clean up. Read
+With GitLab's [Route Maps](review_apps/index.md#route-maps) you can go directly
+from source files to public pages on the environment set for Review Apps.
+
+From then on, you have a full development cycle, where your app is tested, built, deployed
+as a Review App, deployed to a staging server once the merge request is merged,
+and finally manually deployed to the production server. This is a simple workflow,
+but when you have multiple developers working on a project
+at the same time, each of them pushing to their own branches, dynamic environments are
+created all the time. In which case, you probably want to do some clean up. Read
 next how environments can be stopped.
 
 ## Stopping an environment
diff --git a/doc/ci/img/view_on_env_blob.png b/doc/ci/review_apps/img/view_on_env_blob.png
index acc457fbb38..acc457fbb38 100644
--- a/doc/ci/img/view_on_env_blob.png
+++ b/doc/ci/review_apps/img/view_on_env_blob.png
diff --git a/doc/ci/img/view_on_env_mr.png b/doc/ci/review_apps/img/view_on_env_mr.png
index 2c0bd25a4f2..2c0bd25a4f2 100644
--- a/doc/ci/img/view_on_env_mr.png
+++ b/doc/ci/review_apps/img/view_on_env_mr.png
diff --git a/doc/ci/img/view_on_mr_widget.png b/doc/ci/review_apps/img/view_on_mr_widget.png
index efe023b07b5..efe023b07b5 100644
--- a/doc/ci/img/view_on_mr_widget.png
+++ b/doc/ci/review_apps/img/view_on_mr_widget.png
diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md
index 64be011008e..8b3a7b63e62 100644
--- a/doc/ci/review_apps/index.md
+++ b/doc/ci/review_apps/index.md
@@ -102,3 +102,88 @@ The following are example projects that use Review Apps with:
 - [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift).
 
 See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example.
+
+## Route Maps
+
+> Introduced in GitLab 8.17. In GitLab 11.5 the file links
+are surfaced to the merge request widget.
+
+Route Maps allows you to go directly from source files
+to public pages on the [environment](../environments.md) defined for
+Review Apps. Once set up, the review app link in the merge request
+widget can take you directly to the pages changed, making it easier
+and faster to preview proposed modifications.
+
+All you need to do is to tell GitLab how the paths of files
+in your repository map to paths of pages on your website using a Route Map.
+Once set, GitLab will display **View on ...** buttons, which will take you
+to the pages changed directly from merge requests.
+
+To set up a route map, add a a file inside the repository at `.gitlab/route-map.yml`,
+which contains a YAML array that maps `source` paths (in the repository) to `public`
+paths (on the website).
+
+### Route Maps example
+
+Below there's an example of a route map for [Middleman](https://middlemanapp.com),
+a static site generator (SSG) used to build [GitLab's website](https://about.gitlab.com),
+deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com):
+
+```yaml
+# Team data
+- source: 'data/team.yml' # data/team.yml
+  public: 'team/' # team/
+
+# Blogposts
+- source: /source\/posts\/([0-9]{4})-([0-9]{2})-([0-9]{2})-(.+?)\..*/ # source/posts/2017-01-30-around-the-world-in-6-releases.html.md.erb
+  public: '\1/\2/\3/\4/' # 2017/01/30/around-the-world-in-6-releases/
+
+# HTML files
+- source: /source\/(.+?\.html).*/ # source/index.html.haml
+  public: '\1' # index.html
+
+# Other files
+- source: /source\/(.*)/ # source/images/blogimages/around-the-world-in-6-releases-cover.png
+  public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png
+```
+
+Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, we have a hash map with two keys:
+
+- `source`
+    - a string, starting and ending with `'`, for an exact match
+    - a regular expression, starting and ending with `/`, for a pattern match
+      - The regular expression needs to match the entire source path - `^` and `$` anchors are implied.
+      - Can include capture groups denoted by `()` that can be referred to in the `public` path.
+      - Slashes (`/`) can, but don't have to, be escaped as `\/`.
+      - Literal periods (`.`) should be escaped as `\.`.
+- `public`
+    - a string, starting and ending with `'`.
+      - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`.
+
+The public path for a source path is determined by finding the first
+`source` expression that matches it, and returning the corresponding
+`public` path, replacing the `\N` expressions with the values of the
+`()` capture groups if appropriate.
+
+In the example above, the fact that mappings are evaluated in order
+of their definition is used to ensure that `source/index.html.haml`
+will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`,
+and will result in a public path of `index.html`, instead of
+`index.html.haml`.
+
+Once you have the route mapping set up, it will be exposed in a few places:
+
+- In the merge request widget. The **View app** button will take you to the
+  environment URL you have set up in `.gitlab-ci.yml`. The dropdown will render
+  the first 5 matched items from the route map, but you can filter them if more
+  than 5 are available.
+
+    ![View app file list in merge request widget](img/view_on_mr_widget.png)
+
+- In the diff for a merge request, comparison, or commit.
+
+    !["View on env" button in merge request diff](img/view_on_env_mr.png)
+
+- In the blob file view.
+
+    !["View on env" button in file view](img/view_on_env_blob.png)
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index 9015a964781..2c8a590fc45 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -284,7 +284,11 @@ you can preview the changes submitted to a feature-branch through a merge reques
 in a per-branch basis. No need to checkout the branch, install and preview locally;
 all your changes will be available to preview by anyone with the Review Apps link.
 
-[Read more about Review Apps.](../../../ci/review_apps/index.md)
+With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the
+merge request widget takes you directly to the pages changed, making it easier and
+faster to preview proposed modifications.
+
+[Read more about Review Apps](../../../ci/review_apps/index.md).
 
 ## Pipelines for merge requests