Merge pull request #3581 from commercialhaskell/add-to-yaml-config-docs

yaml_configuration.md coverage for all options

Author: mgsloan

doc/GUIDE.md

@@ -1577,8 +1577,9 @@ what needs to be removed:
 We've already used `stack exec` used multiple times in this guide. As you've
 likely already guessed, it allows you to run executables, but with a slightly
 modified environment. In particular: `stack exec` looks for executables on
-stack's bin paths, and sets a few additional environment variables (like
-`GHC_PACKAGE_PATH`, which tells GHC which package databases to use).
+stack's bin paths, and sets a few additional environment variables (like adding
+those paths to `PATH`, and setting `GHC_PACKAGE_PATH`, which tells GHC which
+package databases to use).
 
 If you want to see exactly what the modified environment looks like, try:
 
@@ -1906,21 +1907,6 @@ __Other tools for comparison (including active and historical)__
 * [cabal-src](https://hackage.haskell.org/package/cabal-src) is mostly irrelevant in the presence of both stack and cabal sandboxes, both of which make it easier to add additional package sources easily. The mega-sdist executable that ships with cabal-src is, however, still relevant. Its functionality may some day be folded into stack
 * [stackage-cli](https://hackage.haskell.org/package/stackage-cli) was an initial attempt to make cabal-install work more easily with curated snapshots, but due to a slight impedance mismatch between cabal.config constraints and snapshots, it did not work as well as hoped. It is deprecated in favor of stack.
 
-## More resources
-
-There are lots of resources available for learning more about stack:
-
-* `stack --help`
-* `stack --version` — identify the version and Git hash of the stack executable
-* `--verbose` (or `-v`) — much more info about internal operations (useful for bug reports)
-* The [home page](http://haskellstack.org)
-* The [stack mailing list](https://groups.google.com/d/forum/haskell-stack)
-* The [the FAQ](faq.md)
-* The [stack wiki](https://github.com/commercialhaskell/stack/wiki)
-* The [haskell-stack tag on Stack Overflow](http://stackoverflow.com/questions/tagged/haskell-stack)
-* [Another getting started with stack tutorial](http://seanhess.github.io/2015/08/04/practical-haskell-getting-started.html)
-* [Why is stack not cabal?](https://www.fpcomplete.com/blog/2015/06/why-is-stack-not-cabal)
-
 
 ## Fun features
 
@@ -1969,11 +1955,11 @@ As a starting point you can use [the "simple" template](https://github.com/comme
 An introduction into template-writing and a place for submitting official templates,
 you will find at [the stack-templates repository](https://github.com/commercialhaskell/stack-templates#readme).
 
-### IDE
+### Editor integration
 
-stack has a work-in-progress suite of editor integrations, to do things like
-getting type information in Emacs. For more information, see
-[stack-ide](https://github.com/commercialhaskell/stack-ide#readme).
+For editor integration, stack has a related project called
+[intero](https://github.com/commercialhaskell/intero).  It is particularly well
+supported by emacs, but some other editors have integration for it as well.
 
 ### Visualizing dependencies
 
@@ -2166,6 +2152,14 @@ build:
   executable-profiling: true
 ```
 
+### Further reading
+
+For more commands and uses, see [the official GHC chapter on
+profiling](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html),
+[the Haskell wiki](https://wiki.haskell.org/How_to_profile_a_Haskell_program),
+and [the chapter on profiling in Real World
+Haskell](http://book.realworldhaskell.org/read/profiling-and-optimization.html).
+
 ### Tracing
 
 To generate a backtrace in case of exceptions during a test or benchmarks run,
@@ -2180,10 +2174,17 @@ using the `--no-strip`, `--no-library-stripping`, and `--no-executable-stripping
 flags to disable the default behavior of removing such information from compiled
 libraries and executables.
 
-### Further reading
+## More resources
 
-For more commands and uses, see [the official GHC chapter on
-profiling](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html),
-[the Haskell wiki](https://wiki.haskell.org/How_to_profile_a_Haskell_program),
-and [the chapter on profiling in Real World
-Haskell](http://book.realworldhaskell.org/read/profiling-and-optimization.html).
+There are lots of resources available for learning more about stack:
+
+* `stack --help`
+* `stack --version` — identify the version and Git hash of the stack executable
+* `--verbose` (or `-v`) — much more info about internal operations (useful for bug reports)
+* The [home page](http://haskellstack.org)
+* The [stack mailing list](https://groups.google.com/d/forum/haskell-stack)
+* The [the FAQ](faq.md)
+* The [stack wiki](https://github.com/commercialhaskell/stack/wiki)
+* The [haskell-stack tag on Stack Overflow](http://stackoverflow.com/questions/tagged/haskell-stack)
+* [Another getting started with stack tutorial](http://seanhess.github.io/2015/08/04/practical-haskell-getting-started.html)
+* [Why is stack not cabal?](https://www.fpcomplete.com/blog/2015/06/why-is-stack-not-cabal)

doc/yaml_configuration.md

@@ -759,7 +759,7 @@ save-hackage-creds: true
 
 Since 1.5.0
 
-# urls
+### urls
 
 Customize the URLs where `stack` looks for snapshot build plans.
 
@@ -774,3 +774,91 @@ urls:
 
 **Note:** The `latest-snapshot-url` field has been deprecated in favor of `latest-snapshot`
 and will be removed in a future version of `stack`.
+
+### jobs
+
+Specifies how many build tasks should be run in parallel. This can be overloaded
+on the commandline via `-jN`, for example `-j2`.  The default is to use the
+number of processors reported by your CPU.  One usage for this might be to avoid
+running out of memory by setting it to 1, like this:
+
+```yaml
+jobs: 1
+```
+
+### work-dir
+
+Specifies relative path of work directory (default is `.stack-work`. This can
+also be specified by env var or cli flag, in particular, the earlier items in
+this list take precedence:
+
+1. `--work-dir DIR` passed on the commandline
+2. `work-dir` in stack.yaml
+3. `STACK_WORK` environment variable
+
+Since 0.1.10.0
+
+### skip-msys
+
+Skips checking for and installing msys2 when stack is setting up the
+environment.  This is only useful on Windows machines, and usually doesn't make
+sense in project configurations, just in `config.yaml`.  Defaults to `false`, so
+if this is used, it only really makes sense to use it like this:
+
+```yaml
+skip-msys: true
+```
+
+Since 0.1.2.0
+
+### concurrent-tests
+
+This option specifies whether test-suites should be executed concurrently with
+each-other. The default for this is true, since this is usually fine and it
+often means that tests can complete earlier. However, if some test-suites
+require exclusive access to some resource, or require a great deal of CPU or
+memory resources, then it makes sense to set this to `false` (the default is
+`true`).
+
+```yaml
+concurrent-tests: false
+```
+
+Since 0.1.2.0
+
+### extra-path
+
+This option specifies additional directories to prepend to the PATH environment
+variable.  These will be used when resolving the location of executables, and
+will also be visible in the `PATH` variable of processes run by stack.
+
+For example, to prepend `/path-to-some-dep/bin` to your PATh:
+
+```yaml
+extra-path:
+- /path-to-some-dep/bin
+```
+
+One thing to note is that other paths added by stack - things like the project's
+bin dir and the compiler's bin dir - will take precedence over those specified
+here (the automatic paths get prepended).
+
+Since 0.1.4.0
+
+### local-programs-path
+
+This overrides the location of the programs directory, where tools like ghc and
+msys get installed.
+
+On most systems, this defaults to a folder called `programs`
+within the stack root directory. On windows, if the `LOCALAPPDATA` environment
+variable exists, then it defaults to `$LOCALAPPDATA/Programs/stack/`, which
+follows windows conventions.
+
+Since 1.3.0
+
+### default-template
+
+This option specifies which template to use with `stack new`, when none is
+specified. The default is called `new-template`. The other templates are listed
+in [the stack-templates repo](https://github.com/commercialhaskell/stack-templates/).