Merge pull request #2053 from SvenDowideit/v1.1.x-docs-prep

V1.1.x docs prep

.dockerignore

@@ -15,3 +15,4 @@ tests/integration/.tox
 #.dapper
 vendor/*/*/*/.git
 tmp
+docs/_site

docs/Dockerfile

@@ -0,0 +1,5 @@
+FROM rancher/rancher.github.io:build AS builder
+
+FROM nginx
+COPY --from=builder /build/_site /usr/share/nginx/html/docs
+COPY --from=builder /build/favicon.png /usr/share/nginx/html/favicon.png

docs/Dockerfile.build

@@ -0,0 +1,23 @@
+FROM jekyll/jekyll:3.4 AS builder
+WORKDIR /build
+COPY Gemfile /build
+COPY Gemfile.lock /build
+COPY _config.yml /build
+RUN jekyll build
+COPY . /build
+
+ENV OSVERSION v1.1
+
+# IMPORTANT: this line moves the development docs to where they would be in rancher/rancher.gihub.io
+RUN mv os os-orig \
+    && mkdir -p os/$OSVERSION/en \
+    && mv os-orig/* os/$OSVERSION/en/
+
+# Set up the latest pages that get converted into redirects
+ENV OS_DOCS_LATEST $OSVERSION
+RUN mkdir -p os/latest/en \
+    && cp -r os/$OSVERSION/en/* os/latest/en/ \
+    && cp -r os/$OSVERSION/en/* os/latest/ \
+    && cp -r os/$OSVERSION/en/* os/
+
+RUN jekyll build

docs/Gemfile.lock

@@ -86,7 +86,7 @@ GEM
       gemoji (~> 2.0)
       html-pipeline (~> 2.2)
       jekyll (>= 2.0)
-    json (1.8.1)
+    json (1.8.2)
     kramdown (1.9.0)
     liquid (3.0.6)
     listen (3.0.4)
@@ -128,4 +128,4 @@ DEPENDENCIES
   json
 
 BUNDLED WITH
-   1.11.2
+   1.15.3

docs/Makefile

@@ -0,0 +1,27 @@
+.PHONY: default build build-nginx run live
+
+default: build build-nginx run
+
+# this target sets up Jekyll, and uses it to build html
+build:
+	docker build -t rancher/rancher.github.io:build -f Dockerfile.build .
+
+# this target uses the Jekyll html image in a multistage Dockerfile to build a small nginx image
+build-nginx:
+	docker build -t rancher/rancher.github.io .
+
+run: build-nginx
+	docker run --rm -p 80:80 rancher/rancher.github.io
+
+# this target will use the jekyll image and bind mount your local repo, when you modify a file, the html will be automatically rebuilt. (the redirects from latest won't work)
+# You can also examine the output html in the _sites dir.
+live:
+	docker run --rm -it -p 80:4000 \
+		-v $(PWD)/os:/build/os/v1.1/en \
+		-v $(PWD)/_site:/build/_site \
+		rancher/rancher.github.io:build jekyll serve -w -P 4000 --incremental
+
+clean:
+	rm -rf _sites
+	docker rmi rancher/rancher.github.io
+	docker rmi rancher/rancher.github.io:build

docs/README.md

@@ -1,20 +1,141 @@
-# Documentation for the `master` version of `rancher/os`
+# Rancher Labs Documentation
 
-This dir is _not_ the documentation for any released version of RancherOS.
-You can find that at the [Rancher Labs Documentation site](https://docs.rancher.com) and
-specifically for [RancherOS](https://docs.rancher.com/os/).
+This README file includes information pertaining to the documentation project for both Rancher and Rancher OS.
 
-When there are Pull Requests to the `rancher/os` repository that affect the user (or developer),
-then it should include changes to the documenation in this directory.
+## Rancher
 
-When we make a new release of RancherOS, the `docs/os` dir will be copied into the `rancher/rancher.github.io`
-repository to be accessible by users.
+Rancher is an open source project that provides a complete platform for operating Docker in production. It provides infrastructure services such as multi-host networking, global and local load balancing, and volume snapshots. It integrates native Docker management capabilities such as Docker Machine and Docker Swarm. It offers a rich user experience that enables devops admins to operate Docker in production at large scale.
 
-## Previewing your changes
+## Rancher OS
 
-You can either build and view your docs locally by running `make docs`, or you can
-set your fork of the `rancher/os` repository to render your `master` using `GitHub Pages`.
+Operating system composed entirely of Docker containers. Everything in RancherOS is a container managed by Docker. This includes system services such as udev and syslog. RancherOS includes only the bare minimum amount of software needed to run Docker.
 
-To set up `GitHub Pages`, browse to your fork, then to the `Settings` - under `GitHub Pages`, set the `Source`
-to `master branch /docs folder` and hit the `Save` button. GitHub will tell you the URL at which the
-documenation can be read.
+## Rancher Labs Documentation website
+
+Rancher documentation is available at <http://rancher.com/docs/rancher/>.
+
+As Rancher has gone GA, we've added in version control. The default Rancher docs site will always be referring to the latest release. We will branch off specific versions of Rancher that are deemed GA, which would also be tagged as `rancher/server:stable`.
+
+Currently, we've added support for Chinese version of the docs site per community request. Currently, Rancher will not be actively translating the docs site, but we welcome PRs.
+
+Rancher OS documentation is available at <http://rancher.com/docs/os/>.
+
+## Contributing to Rancher Labs Documentation Project
+
+### About Rancher Labs Documentation Site
+
+Rancher Labs documentation is hosted on GitHub Pages and published online by using Jekyll, an easy blog-aware static website generator. For more details on how to set up Jekyll, we recommend you to read <https://help.github.com/articles/using-jekyll-with-pages/>. If you are using Windows, we strongly advise you to follow the instruction given at <http://jekyllrb.com/docs/windows/>.
+
+For information on editing `.md` files (Markdown), refer to <https://daringfireball.net/projects/markdown/syntax>.
+
+Or you can use the `make live` Makefile target (or run `docker run --rm -it -p 80:4000 -v $(PWD):/build rancher/rancher.github.io:build jekyll serve -w -P 4000 --incremental` by hand to use the Jekyll build image used for our production pipeline.
+
+### Setting up the Git Environment
+
+In your browser, navigate to <https://github.com/rancher/rancher.github.io>.
+
+Fork this repository by clicking the Fork button on the upper right-hand side. A fork of the repository is generated for you. On the right-hand side of the page of your fork, under 'HTTPS clone URL', copy the URL by clicking the Copy to clipboard icon.
+
+On your computer, follow these steps to setup a local repository to start working on the documentation:
+
+```shell
+git clone https://github.com/YOUR_ACCOUNT/rancher.github.io.git
+cd rancher.github.io
+git remote add upstream https://github.com/rancher/rancher.github.io
+git checkout master
+git fetch upstream
+git merge upstream/master
+```
+
+### Updating the Files
+
+We recommend you to create a new branch to update the documentation files and that you do not disturb the master branch, other than pulling in changes from `upstream/master`.
+For example, you create a branch, `dev`, on your computer to make changes locally to the documentation. This `dev` branch will be your local repository which then be pushed to your forked repository on GitHub where you will create a Pull Request for the changes to be committed into the official documentation.
+
+It is a healthy practice to create a new branch each time you want to contribute to the documentation and only track the changes for that pull request in this branch.
+
+```shell
+git checkout -b dev
+```
+
+The argument `-b dev` creates a new branch named `dev`. Now you can make necessary changes to the documentation.
+
+```shell
+git add .
+git commit -a -m "commit message for your changes"
+```
+
+You can optionally run Jekyll locally on your computer to be able to see the final result of your modifications and you write them. For that, use the command below. You can refer to [Jekyll's official website](https://jekyllrb.com/) for more details.
+
+```shell
+jekyll serve
+```
+
+Additionally, you can use the provided `Makefile` to build and test in a Docker container:
+
+```shell
+make live
+```
+
+### Merging upstream/master into Your Local Branch (`dev`)
+
+Maintain an up-to-date master branch in your local repository. Merge the changes on a daily basis from the `upstream/master` (the official documentation repository) into your local repository.
+
+Ensure that you do complete this activity before you start working on a feature as well as right before you submit your changes as a pull request.
+
+You can also do this process periodically while you work on your changes to make sure that you are working off the most recent version of the documentation.
+
+```shell
+# Checkout your local 'master' branch.
+git checkout master
+
+# Synchronize your local repository with 'upstream/master', so that you have all the latest changes.
+git fetch upstream
+
+# Merge the latest changes from the 'upstream/master' into your local 'master' branch to make it up-to-date.
+git merge upstream/master
+
+# Checkout your local development branch (e.g.: 'dev').
+git checkout dev
+
+# Pull the latest changes into your local development branch.
+git pull master
+```
+
+### Checklist for contributions
+
+Please check the following list before you submit a Pull Request to make sure we can approve it right away!
+
+* Check if your change applies to more than one version, and if so, please make the same change in other versions as well. (Rancher only)
+* If your change only applies to a minor version, make sure it is specified in the text, i.e. `Available as of Rancher v1.6.6` or `Available as of RancherOS v1.1.0`.
+* If your change is regarding an item in the `rancher-catalog`, make sure the change is also applied in the README there.
+
+### Making a Pull Request on GitHub
+
+**Important:** Ensure that you have merged `upstream/master` into your dev branch before you do the following.
+
+After you have made necessary changes to the documentation and are ready to contribute them, create a Pull Request on GitHub. You do it by pushing your changes to your forked repository (usually called `origin`) and then initiating a pull request.
+
+```
+git push origin master
+git push origin dev
+```
+
+Now follow the steps below to initiate a Pull request on GitHub.
+
+1.  Navigate your browser to your forked repository: <https://github.com/YOUR_ACCOUNT/rancher.github.io.git>.
+1.  Click the *Compare & pull request* button on the upper side of the forked repository.
+1.  Enter a clear description for the changes you have made.
+1.  Click *Send Pull Request*.
+
+If you are asked to make modifications to your proposed changes, make the changes locally on your `dev` branch and push the changes. The Pull Request will be automatically updated.
+
+### Cleaning up the Local Repository
+
+You no longer need the `dev` branch after the changes have been committed into `upstream/master`. If you want to make additional documentation changes, restart the process with a new branch.
+
+```
+git checkout master
+git branch -D dev
+git push origin :dev
+```

docs/_config.yml

@@ -1,12 +1,6 @@
 name: Rancher Documentation
 description: Documentation for Rancher
 
-
-URL: http://rancher.github.io
-baseurl: ""
-
-exclude: []
-
 markdown: kramdown
 highlighter: rouge
 kramdown:
@@ -16,3 +10,44 @@ permalink: pretty
 
 gems:
   - jekyll-redirect-from
+
+URL: "http://rancher.com"
+baseurl: "/docs"
+
+# RancherOS defaults
+defaults:
+  -
+    # os/quick-start-guide/ should redirect to os/v1.0/en/quick-start-guide
+    scope:
+      path: "os"
+    values:
+      layout: "os-redirect"
+      version: v1.1
+      lang: en
+  -
+    # os/latest/quick-start-guide/ should redirect to os/v1.0/en/quick-start-guide
+    scope:
+      path: "os/latest"
+    values:
+      layout: "os-latest-redirect"
+  -
+    # os/latest/en/quick-start-guide/ should redirect to os/v1.0/en/quick-start-guide
+    scope:
+      path: "os/latest/en"
+    values:
+      layout: "os-latest-en-redirect"
+  -
+    scope:
+      path: "os/v1.0"
+    values:
+      layout: "os-default-v1.0"
+      version: v1.0
+      osbaseurl: "/docs/os/v1.0/en"
+  -
+    scope:
+      path: "os/v1.1"
+    values:
+      layout: "os-default-v1.1"
+      version: v1.1
+      osbaseurl: "/docs/os/v1.1/en"
+

docs/_includes/footer.html

@@ -1,32 +1,41 @@
-</div>
+      </div>
 
-<div class="col span-8">
-    <div class="content-container">
-
-        {{ content }}
+      <div class="col span-8">
+        <div class="content-container">
+          {{ content }}
 
-<footer class="clearfix">
-    <div class="copyright pull-left" >Copyright &copy; 2017  <a href="http://rancher.com">Rancher Labs</a>. All Rights Reserved.</div>
-        <a class="btn btn-primary pull-right" href="https://github.com/rancher/rancher.github.io/tree/master/{{page.path }}">Edit this page <i class="fa fa-pencil"></i></a>
+          <footer class="clearfix">
+            <div class="copyright pull-left">Copyright &copy; 2014-2017 <a href="http://rancher.com">Rancher Labs</a>.  All Rights Reserved.</div>
+            <a class="btn btn-primary pull-right" href="https://github.com/rancher/rancher.github.io/tree/master/{{page.path }}">Edit this page <i class="fa fa-pencil"></i></a>
+          </footer>
+        </div>
+      </div>
     </div>
-</footer>
-</div>
-</div>
-</div>
 
-<!-- Start of Async HubSpot Analytics Code -->
-<script type="text/javascript">
-(function(d,s,i,r) {
-if (d.getElementById(i)){return;}
-var n=d.createElement(s),e=d.getElementsByTagName(s)[0];
-n.id=i;n.src='//js.hs-analytics.net/analytics/'+(Math.ceil(new Date()/r)*r)+'/468859.js';
-e.parentNode.insertBefore(n, e);
-})(document,"script","hs-analytics",300000);
-</script>
-<!-- End of Async HubSpot Analytics Code -->
+    <script src="{{site.baseurl}}/vendor/jquery.js?t={{site.time}}"></script>
+    <script src="{{site.baseurl}}/js/jquery.slicknav.min.js?t={{site.time}}"></script>
+    <script src="{{site.baseurl}}/js/rancher-docs.js?t={{site.time}}"></script>
 
-<script src="{{site.baseurl}}/vendor/jquery.js?t={{site.time}}"></script>
-<script src="{{site.baseurl}}/js/jquery.slicknav.min.js?t={{site.time}}"></script>
-<script src="{{site.baseurl}}/js/rancher-docs.js?t={{site.time}}"></script>
-</body>
+    <!-- Start of Google Analytics -->
+    <script>
+      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+        m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+            })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+      ga('create', 'UA-56382716-3', 'auto');
+        ga('send', 'pageview');
+    </script>
+    <!-- End of Google Analytics -->
+
+    <!-- Start of Async HubSpot Analytics Code -->
+    <script type="text/javascript">
+    (function(d,s,i,r) {
+    if (d.getElementById(i)){return;}
+    var n=d.createElement(s),e=d.getElementsByTagName(s)[0];
+    n.id=i;n.src='//js.hs-analytics.net/analytics/'+(Math.ceil(new Date()/r)*r)+'/468859.js';
+    e.parentNode.insertBefore(n, e);
+    })(document,"script","hs-analytics",300000);
+    </script>
+    <!-- End of Async HubSpot Analytics Code -->
+  </body>
 </html>