Merge pull request #718 from wallw-bits/docs-update-windows-instructions

docs(rtd): update windows instructions

.gitattributes

@@ -0,0 +1,15 @@
+# Set the default behavior in the event that core.autocrlf is not set
+* text eol=lf
+
+*.dbf binary
+*.gif binary
+*.gpx binary
+*.ico binary
+*.jpg binary
+*.kmz binary
+*.pdf binary
+*.png binary
+*.shp binary
+*.woff binary
+*.woff2 binary
+*.zip binary

README.md

@@ -23,7 +23,7 @@ Questions? Ask them in the [forum](https://groups.google.com/forum/#!forum/opens
 * Node/NPM
 
 ## Getting Started
-OpenSphere is natively developed on Linux and should run great on OS X and typical Linux distributions. Windows support is limited, as the build system requires a Linux shell. Windows 10 introduced the Windows Subsystem for Linux (WSL) which works great, see [here](windows.md) for instructions on setting up a Windows 10/WSL environment to work on OpenSphere projects. Other Windows distributions, perhaps try Cygwin or Linux via a VM or Docker container.
+OpenSphere is natively developed on Linux and should run great on OS X and typical Linux distributions. See [Windows Development](http://opensphere.readthedocs.io/en/latest/windows_development.html) for instructions for building on Windows.
 
 ### Yarn
 
@@ -111,7 +111,7 @@ By default the ```baseURL``` is set to the local compiled build: http://localhos
 
 ### Running Tests
 Run all tests via the command line ```yarn test:cypress-all```, individual specs via the command line ```yarn test:cypress-spec folder/test.spec.js```, or run tests interactively with the [Test Runner](https://docs.cypress.io/guides/core-concepts/test-runner.html) via ```yarn test:cypress```.
-    
+
 
 ### Adding and modifying tests
 

docs/getting_started.rst

@@ -21,7 +21,10 @@ Prerequisites
 - Chrome Browser (59+ required in default tests; plus you probably want this for development)
 - Firefox Browser (57+ required in default tests)
 
+Windows developers see `Windows Development`_
+
 .. _Yarn: https://yarnpkg.com
+.. _Windows Development: windows_development.html
 
 Ensure that the executables ``git``, ``node``, and ``java`` are in your ``PATH``.
 
@@ -71,7 +74,7 @@ While not required, we highly recommend setting up nginx or Apache httpd to serv
 The Build
 *********
 
-Note: The build does not work in Windows. Consider using an Ubuntu Docker container or VM to run the build.
+Note: The build does not work natively in Windows. See `Windows Development`_ for instructions.
 
 OpenSphere has all of its build targets as npm scripts. Therefore you can run any particular target by running:
 
@@ -165,9 +168,9 @@ Any contributions to OpenSphere should avoid breaking current tests and should i
 Git Commits
 ***********
 
-When making local commits, there are checks (implemented as git pre-commit hooks) to verify that your commit message matches the `Conventional Commits`_ conventions. 
+When making local commits, there are checks (implemented as git pre-commit hooks) to verify that your commit message matches the `Conventional Commits`_ conventions.
 Basically, you need use the form ``<type>(<scope>): <subject>``, for example something like: ``fix(docs): Updated Getting Started to describe git commits``.
-The valid types are: ``feat``, ``fix``, ``docs``, ``style``, ``refactor``, ``perf``, ``test``, ``build``, ``ci``, ``chore`` and ``revert``. Scope is optional, and 
+The valid types are: ``feat``, ``fix``, ``docs``, ``style``, ``refactor``, ``perf``, ``test``, ``build``, ``ci``, ``chore`` and ``revert``. Scope is optional, and
 should cover the particular part of opensphere that you are working on.
 
 .. _Conventional Commits: https://www.conventionalcommits.org
@@ -209,6 +212,7 @@ The compiler will attempt to minify/rename everything not in a string. For the m
 Broken Example:
 
 .. code-block:: javascript
+   :linenos:
 
     /**
      * @param {!angular.Scope} $scope The scope
@@ -225,6 +229,7 @@ Broken Example:
     };
 
 .. code-block:: html
+   :linenos:
 
     <!-- Angular template -->
     <span ng-show="ctrl.isPositive(value)">{{value}} is positive</span>
@@ -234,6 +239,8 @@ This will work great in debug mode (no minification), but will fail in compiled
 Fixed Example:
 
 .. code-block:: javascript
+   :linenos:
+   :emphasize-lines: 5, 10
 
     /**
      * @param {!angular.Scope} $scope The scope
@@ -244,14 +251,14 @@ Fixed Example:
 
     /**
      * @param {number} value
+     * @export
      */
     package.DirCtrl.prototype.isPositive = function(value) {
       return value > 0;
     };
-    // we highly recommend making this a snippet
-    goog.exportProperty(package.DirCtrl.prototype, 'isPositive', package.DirCtrl.prototype.isPositive);
 
 .. code-block:: html
+   :linenos:
 
     <!-- Angular template -->
     <span ng-show="ctrl.isPositive(value)">{{value}} is positive</span>

docs/index.rst

@@ -23,6 +23,7 @@ The code is open source, and `available on GitHub`_.
 
    contributing
    getting_started
+   windows_development
    guides/app_guide
    guides/plugin_guide
    guides/settings_guide

docs/windows_development.rst

@@ -0,0 +1,86 @@
+.. _windows_development:
+
+Windows Development
+###################
+
+Our build does not run natively on Windows due to its requirement of a POSIX shell and some of
+the core utilities such as ``cat``, ``cp``, ``echo``, ect. However, you can build and develop
+OpenSphere on Windows with any of the following:
+
+- Git Bash (included with Git for Windows)
+- Cygwin_
+- `Windows Subsystem for Linux`_
+- Docker
+- Linux VM
+
+These instructions will take the simplest approach by using Git Bash.
+
+.. _Cygwin: https://www.cygwin.com
+.. _Windows Subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/install-win10
+
+
+Prerequisites
+=============
+
+Install git, java, node, and yarn. We recommend using Chocolatey_, a package manager for Windows.
+After installing Chocolatey_, run the following in a command prompt as an administrator:
+
+.. _Chocolatey: https://chocolatey.org/
+
+.. code-block:: none
+
+  choco install git jre8 nvm yarn
+  refreshenv
+  nvm install 10.16.2
+  nvm use 10.16.2
+
+Now we will check our work:
+
+.. code-block:: none
+
+  git --version
+  java -version
+  node --version
+  npm --version
+  yarn --version
+
+Git for Windows installs "Git Bash". Search for it in the Start Menu and fire it up.
+
+
+Setup
+=====
+
+Setup the project workspace and clone the project:
+
+.. code-block:: none
+
+  cd <your workspace directory>
+  git clone https://github.com/ngageoint/opensphere-yarn-workspace
+  cd opensphere-yarn-workspace/workspace
+  git clone https://github.com/ngageoint/opensphere
+  yarn install
+  cd opensphere
+
+Now you are about ready to build opensphere. However, we need to tell the NPM script runner to use BASH
+rather than whatever it typically uses on Windows.
+
+.. code-block:: none
+
+  npm config set script-shell "C:/Program Files/git/bin/bash.exe"
+
+If you have other node projects on your machine and do not wish for this to pollute them, then consider adding
+that configuration to a ``.npmrc`` file local to the project.
+
+Also fix your line ending configuration for git (necessary if using Git Bash but not if you are using a full POSIX environment such as Cygwin_):
+
+.. code-block:: none
+
+  git config core.autocrlf input
+
+Now build:
+
+.. code-block:: none
+
+  npm run build
+
+At the time of this writing, ``yarn`` has a bug with the ``script-shell`` config. A fix has already been committed and should make their next non-patch release. After that you can use ``yarn run build`` or just ``yarn build`` if  you prefer.