Repository: xonsh/xonsh
Pull request: Add pip install xonsh [full] and rewrite install doc
Resolves #3622 

Adds extras tag [full], which installs xonsh with pygments, prompt-toolkit and distro, with the intent that that's what most users will want.

Also update installation section of docs to include this option, but take the opportunity for a thorough rewrite:  
collapse separate linux, osx and windows guides into one cross-platform install and config flow; add doc for the 2 startup wizards, modernize the Windows section to prefer Windows Terminal as your getting-started config.    

These doc changes are opinionated and potentially controversial, which is not my intent.  So I'm prepared to redo based on feedback. 

Problem statement:
Please, add 'prompt_toolkit' to general requirements.
I'm having errors in 'abbrevs' and a lot of things printed at the terminal startup.
I use Manjaro Linux and neither the system package, nor the "Arch User Repository" package, nor the package in the "pip" requires the installation of "prompt_toolkit" by DEFAULT.
If possible, as it is undoubtedly an important package, add as required dependency.
In a last look at all the documentation, I found this syntax in the installation instructions for linux: "xonsh[ptk,linux]". I would like to say that, even for those who have a basic knowledge of python, this syntax is a bit obscure. If possible, it would be good to clarify the point.
Thank you very much for this wonderful project.

Hints from issue discussion:
I would protest that the extras syntax is obscure for Pythonistas. It is extremely common and used by many packages with optional dependencies.

The rest of it is up for debate. It is arguable whether various packages should or should not include it. For example, I maintain the containers: `xonsh/xonsh` and `xonsh/action` do not include PTK because the former is meant to be a minimal base package and the latter is meant for automation. `xonsh/interactive` however does include ptk (as well as pygments) because it is meant for humans.

I believe the general logic is to allow xonsh to be used with reduced dependencies (readline only, without ptk+pygments). The way python packaging works is that you can't specify configurations with less dependencies--you can specify extras to extend functionality with new dependencies, but to specify a configuration with less dependencies you'd need a new package.

As with most FOSS, who is responsible for what packages where is a complex question--I think we directly maintain just the PyPI, Conda, and AppImage packages.
On conda-forge a lot of packages are split into xxx-base/xxx to handle the case with optional dependencies. For example [matplotlib ](https://github.com/conda-forge/matplotlib-feedstock/blob/master/recipe/meta.yaml#L20) and seaborn.

I don't think I have seen similar concepts on PyPI but maybe we should think about that. `xonsh` could be a meta package with all dependencies and `xonsh-base` the bare minimum. 
> I don't think I have seen similar concepts on PyPI but maybe we should think about that. `xonsh` could be a meta package with all dependencies and `xonsh-base` the bare minimum.

That's an interesting idea. I don't remember seeing such packages at PyPI either.

As for making _prompt_toolkit_ a general "hard" requirement, I also vote "nay". While it certainly is beneficial to interactive users, it is absolutely unnecessary for non-interactive use.
I don't use Manjaro myself, but since it's an Arch-based distro, I'm almost sure, that their Xonsh package lists _python-prompt_toolkit_ as an optional dependency.
Is Xonsh to the point that prompt_toolkit should be a hard requirement for *interactive* use?  As in, you get a run-time error if you invoke Xonsh interactively and don't have it?  And the configuration wizard offers a warning and / or help if you choose a color scheme or otherwise imply you're interested in interactive use but don't have PTK?

[PTK supports dumb terminal mode](https://github.com/prompt-toolkit/python-prompt-toolkit/pull/1035) if you are running in a really restricted environment, but it works fine on all the mainline environments that you'd use interactively. Maybe readline shell (and the maintenance burden) has outlived its usefulness...
I think we have users that do use the readline shell?

The main use of the readline interface is that it is lighter than the ptk interface. (Although honestly, if weight is a concern, you should probably not use xonsh.)
The basic reasoning here is that xonsh should be able to run on the standard library-only, so that if you have Python, you have  your shell
@scopatz  What about if we vend PTK similar to what we do with PLY. 

We could use the user installed PTK if it is available and recent enough. Otherwise fall back the version we vend. 

It would be a annoyin to maintain, but it would improve user experience on systems where PTK is not installed. I just don't know if it would be considered bad practice. 
I think that would be OK to do.  Annoying to maintain, but it might be worth it.
@scopatz I have been looking at vending PTK. 

I place it `xonsh/vended_ptk/prompt_toolkit`, and then I add the `vended_ptk` folde to the python path if "prompt_toolkit" is not installed. 

``` python
def vend_prompt_toolkit_if_not_available():
    spec = importlib.util.find_spec("prompt_toolkit")
    if spec is None:
        sys.path.append(str(pathlib.Path(__file__).with_name("vended_ptk").resolve()))
```

Do you know of an other way to import a vended subpackages as it were a toplevel module in `sys.modules`. I don't like the use of `__file__` in this implementation. 
Is there a meaningful difference between "vending" and "primary distributables include dependencies"?

Commit message: news!

Patch to review:
diff --git a/.gitignore b/.gitignore
index 6382119f29..f16d3f9f76 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,7 +37,8 @@ bin/
 /lib/
 include/
 venv/
-.venv/
+.venv*/
+
 
 # Mac
 .DS_Store
diff --git a/docs/appimage.rst b/docs/appimage.rst
index d5bae56fd2..61b5d179b5 100644
--- a/docs/appimage.rst
+++ b/docs/appimage.rst
@@ -1,5 +1,5 @@
-Portable rootless xonsh build on AppImage
-=========================================
+Via AppImage
+=============
 
 `AppImage <https://appimage.org/>`_ is a format for distributing portable software on Linux without needing superuser permissions to install the application. It tries also to allow Linux distribution-agnostic binary software deployment for application developers, also called Upstream packaging. 
 
diff --git a/docs/conf.py b/docs/conf.py
index cd3f917bae..bbe6224321 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -440,5 +440,5 @@ def make_events():
 def setup(app):
     from xonsh.pyghooks import XonshConsoleLexer
 
-    app.add_lexer("xonshcon", XonshConsoleLexer)
+    app.add_lexer("xonshcon", XonshConsoleLexer())
     app.add_css_file("custom.css")
diff --git a/docs/containers.rst b/docs/containers.rst
index 500734f665..fc2c1c2e0c 100644
--- a/docs/containers.rst
+++ b/docs/containers.rst
@@ -1,7 +1,7 @@
-Containers
-==========
+Run from container
+==================
 
-xonsh publishes a handful of containers, primarily targeting CI and automation use-cases. All of them are published on `Docker Hub <https://hub.docker.com/u/xonsh>`__.
+Xonsh publishes a handful of containers, primarily targeting CI and automation use cases. All of them are published on `Docker Hub <https://hub.docker.com/u/xonsh>`__.
 
 * ``xonsh/xonsh``: A base container providing basic xonsh
 * ``xonsh/interactive``: xonsh with additions for people
diff --git a/docs/customization.rst b/docs/customization.rst
index 89107d2323..47aa2fc322 100644
--- a/docs/customization.rst
+++ b/docs/customization.rst
@@ -234,30 +234,4 @@ variables:
 ...use xonsh inside Emacs?
 ----------------------------------
 
-**Option A: Comint buffer**
-
-You can use xonsh as your `interactive shell in Emacs
-<https://www.gnu.org/software/emacs/manual/html_node/emacs/Interactive-Shell.html>`_
-in a Comint buffer. This way you keep all the Emacs editing power
-in the shell, but you loose xonsh's completion feature.
-
-Make sure you install xonsh with readline support and in your
-``.xonshrc`` file define
-
-.. code-block:: xonsh
-
-    $SHELL_TYPE = 'readline'
-
-Also, in Emacs set ``explicit-shell-file-name`` to your xonsh executable.
-
-**Option B: Ansi-term buffer**
-
-The second option is to run xonsh in an Ansi-term buffer inside
-Emacs. This way you have to switch modes if you want do Emacs-style
-editing, but you keep xonsh's impressive completion.
-
-For this it is preferred to have xonsh installed with the
-prompt-toolkit. Then you can leave ``$SHELL_TYPE`` at its default.
-
-Emacs will prompt you for the path of the xonsh exeutable when you
-start up ``ansi-term``.
+see `emacs <editors.html>`_.
diff --git a/docs/dependencies.rst b/docs/dependencies.rst
deleted file mode 100644
index c5db3c31af..0000000000
--- a/docs/dependencies.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-Dependencies
-------------
-Xonsh currently has the following external dependencies,
-
-*Run Time:*
-
-    #. Python v3.5+
-
-Pip supports "extra" dependencies in the form of ``xonsh[ptk,linux]``, where
-the list in the brackets identify the optional features
-
-Xonsh currently has the following extras
-
-    #. ``ptk``: prompt-toolkit >= 2.0: *advanced readline library, line-editing*
-    #. ``pygments``: pygments >=2.2: *syntax-highlighting*
-    #. ``proctitle``: setproctitle: *change the title of terminal to reflect the current subprocess*
-    #. ``linux``: distro: *linux specific platform information*
-    #. ``mac``: gnureadline: *GNU's featureful version of readline*
-
-In addition, xonsh integrates with Jupyter, an in-browser REPL, enabling the use of xonsh in jupyter notebooks
-
-Development Dependencies
-------------------------
-
-If you want to develop xonsh, it is extremely recommended to install the dependencies listed in `requirements/docs.txt <https://github.com/xonsh/xonsh/blob/master/requirements/docs.txt>`_ (to generate documentation) and `requirements/tests.txt <https://github.com/xonsh/xonsh/blob/master/requirements/tests.txt>`_ (to run the test suite).
diff --git a/docs/editors.rst b/docs/editors.rst
index b5a3a03d08..81df39d373 100644
--- a/docs/editors.rst
+++ b/docs/editors.rst
@@ -9,6 +9,9 @@ Editor Support
 Emacs
 =====
 
+Emacs Xonsh mode
+----------------
+
 There is an emacs mode for editing xonsh scripts available from the
 `MELPA repository`_. If you are not familiar see the installation
 instructions there.
@@ -21,3 +24,34 @@ Then just add this line to your emacs configuration file:
 
 
 .. _MELPA repository: https://melpa.org/#/xonsh-mode
+
+
+Xonsh Comint buffer
+-------------------
+
+You can use xonsh as your `interactive shell in Emacs
+<https://www.gnu.org/software/emacs/manual/html_node/emacs/Interactive-Shell.html>`_
+in a Comint buffer. This way you keep all the Emacs editing power
+in the shell, but you loose xonsh's completion feature.
+
+Make sure you install xonsh with readline support and in your
+``.xonshrc`` file define
+
+.. code-block:: xonsh
+
+    $SHELL_TYPE = 'readline'
+
+Also, in Emacs set ``explicit-shell-file-name`` to your xonsh executable.
+
+Xonsh Ansi-term buffer
+----------------------
+
+The second option is to run xonsh in an Ansi-term buffer inside
+Emacs. This way you have to switch modes if you want do Emacs-style
+editing, but you keep xonsh's impressive completion.
+
+For this it is preferred to have xonsh installed with the
+prompt-toolkit. Then you can leave ``$SHELL_TYPE`` at its default.
+
+Emacs will prompt you for the path of the xonsh exeutable when you
+start up ``ansi-term``.
diff --git a/docs/installation.rst b/docs/installation.rst
index db2af10a4e..b1701ddc6c 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,20 +1,46 @@
 
-Getting Started
-===============
-
-.. include:: dependencies.rst
+Installation
+============
 
+Prerequisites
+-------------
+* python, V3.6 or later.
+* for interactive use, an ansi (vt100-compatible) terminal application.  On Windows 10, the 
+  separately-installable `Windows Terminal app <https://github.com/microsoft/terminal/releases>`_ 
+  is recommended.
+  
 Installation
 ------------
+Xonsh can be installed via package manager, via appimage or just run from a pre-built container:
 
 .. toctree::
     :titlesonly:
     :maxdepth: 2
 
-    linux
-    osx
-    windows
+    packages
     appimage
     containers
-    customization
+
+
+Installation in specialized environments
+----------------------------------------
+
+.. toctree::
+    :titlesonly:
+    :maxdepth: 2
+
+    jupyter
     editors
+
+Configuration and Customization
+================================
+
+Xonsh uses startup configuration files and provides configuration wizards to help you set them up.
+
+.. toctree::
+    :titlesonly:
+    :maxdepth: 2
+
+    xonshrc
+    customization
+    platform-issues
diff --git a/docs/jupyter.rst b/docs/jupyter.rst
new file mode 100644
index 0000000000..48c255905e
--- /dev/null
+++ b/docs/jupyter.rst
@@ -0,0 +1,4 @@
+Xonsh kernel for Jupyter
+========================
+
+[placeholder]
diff --git a/docs/linux.rst b/docs/linux.rst
deleted file mode 100644
index 14a8c18ac5..0000000000
--- a/docs/linux.rst
+++ /dev/null
@@ -1,123 +0,0 @@
-==========================
-Linux Guide
-==========================
-
-Installation
-============
-
-You can install xonsh using ``conda``, ``pip``, or from source.
-
-**conda:**
-
-.. code-block:: console
-
-    $ conda config --add channels conda-forge
-    $ conda install xonsh
-
-
-**pip:**
-
-.. code-block:: console
-
-    $ pip install xonsh
-
-
-**source:** Download the source `from github <https://github.com/xonsh/xonsh>`_
-(`zip file <https://github.com/xonsh/xonsh/archive/master.zip>`_), then run
-the following from the source directory,
-
-.. code-block:: console
-
-    $ pip install .
-
-
-Debian/Ubuntu users can install xonsh from the repository with:
-
-**apt:**
-
-.. code-block:: console
-
-    $ apt install xonsh
-
-
-Xonsh is available on bionic bever (version 0.6.0) and artful aardvark
-(version 0.5.12).
-
-Fedora users can install xonsh from the repository with:
-
-**dnf:**
-
-.. code-block:: console
-
-    $ dnf install xonsh
-
-
-Arch Linux users can install xonsh from the official community repository with:
-
-**pacman:**
-
-.. code-block:: console
-
-    $ pacman -S xonsh
-
-Note that some of these may require ``sudo``.
-If you run into any problems, please let us know!
-
-.. include:: dependencies.rst
-
-Customization
-=============
-
-See the `xonsh customization guide <customization.html>`_ for more details on setting up ``xonsh``!
-
-
-Possible conflicts with Bash
-============================
-
-Depending on how your installation of Bash is configured, Xonsh may have trouble
-loading certain shell modules. Particularly if you see errors similar to this
-when launching Xonsh:
-
-.. code-block:: console
-
-    bash: module: line 1: syntax error: unexpected end of file
-    bash: error importing function definition for `BASH_FUNC_module'
-    bash: scl: line 1: syntax error: unexpected end of file
-    bash: error importing function definition for `BASH_FUNC_scl'
-    bash: module: line 1: syntax error: unexpected end of file
-    bash: error importing function definition for `BASH_FUNC_module'
-    bash: scl: line 1: syntax error: unexpected end of file
-    bash: error importing function definition for `BASH_FUNC_scl'
-
-...You can correct the problem by unsetting the modules, by adding the following
-lines to your ``~/.bashrc file``:
-
-.. code-block:: console
-
-    unset module
-    unset scl
-
-
-Default Ubuntu .bashrc breaks Foreign Shell Functions
-=====================================================
-Xonsh supports importing functions from foreign shells using the
-`ForeignShellFunctionAlias` class, which calls functions as if they were
-aliases. This is implemented by executing a command that sources the file
-containing the function definition and then immediately calls the function with
-any necessary arguments.
-
-The default user `~/.bashrc` file in Ubuntu 15.10 has the following snippet at
-the top, which causes the script to exit immediately if not run interactively.
-
-.. code-block:: bash
-
-    # If not running interactively, don't do anything
-    case $- in
-        *i*) ;;
-          *) return;;
-    esac
-
-This means that any function you have added to the file after this point will be
-registered as a xonsh alias but will fail on execution. Previous versions of
-Ubuntu have a different test for interactivity at the top of the file that
-yields the same problem.
diff --git a/docs/osx.rst b/docs/osx.rst
deleted file mode 100644
index f0a98a0d30..0000000000
--- a/docs/osx.rst
+++ /dev/null
@@ -1,114 +0,0 @@
-==========================
-OSX Guide
-==========================
-
-Installation
-============
-
-You can install xonsh using a package manager including homebrew, macports, conda, pip, or from source.
-
-**homebrew:**
-
-.. code-block:: console
-
-   $ brew install xonsh
-
-
-**MacPorts:**
-
-.. code-block:: console
-
-   $ sudo port install xonsh
-
-**conda:**
-
-.. code-block:: console
-
-    $ conda config --add channels conda-forge
-    $ conda install xonsh
-
-
-**pip:**
-
-.. code-block:: console
-
-    $ pip3 install xonsh
-
-
-**source:** Download the source `from github <https://github.com/xonsh/xonsh>`_
-(`zip file <https://github.com/xonsh/xonsh/archive/master.zip>`_), then run
-the following from the source directory,
-
-.. code-block:: console
-
-    $ pip3 install xonsh
-
-Extras for macOS
-==================
-readline
---------
-
-On macOS, it is *strongly* recommended to install the ``gnureadline`` library if using the readline shell.  ``gnureadline`` can be installed via pip:
-
-.. code-block:: console
-
-    $ pip3 install gnureadline
-
-Path Helper
------------
-
-macOS provides a `path helper
-<http://www.softec.lu/site/DevelopersCorner/MasteringThePathHelper>`_,
-which by default configures paths in bash and other POSIX or C  shells. Without
-including these paths, common tools including those installed by Homebrew
-may be unavailable. See ``/etc/profile`` for details on how it is done.
-To ensure the path helper is invoked on xonsh (for all users), add the
-following to ``/etc/xonshrc``::
-
-    source-bash $(/usr/libexec/path_helper -s)
-
-To incorporate the whole functionality of ``/etc/profile``::
-
-    source-bash --seterrprevcmd "" /etc/profile
-
-
-
-Tab completion
---------------
-Xonsh has support for using bash completion files on the shell, to use it you need to install the bash-completion package. The regular bash-completion package uses v1 which mostly works, but `occasionally has rough edges <https://github.com/xonsh/xonsh/issues/2111>`_ so we recommend using bash-completion v2.
-
-Bash completion comes from <https://github.com/scop/bash-completion> which suggests you use a package manager to install it, this manager will also install a new version of bash without affecting  /bin/bash. Xonsh also needs to be told where the bash shell file that builds the completions is, this has to be added to $BASH_COMPLETIONS. The package includes completions for many Unix commands.
-
-Common packaging systems for MacOs include
-
- -  Homebrew where the bash-completion2 package needs to be installed.
-
-    .. code-block:: console
-
-       $ brew install bash-completion2
-       
-    This will install the bash_completion file in `/usr/local/share/bash-completion/bash_completion` which is in the current xonsh code and so should just work.
-
- - `MacPorts <https://trac.macports.org/wiki/howto/bash-completion>`_ where the bash-completion port needs to be installed.
-
-   .. code-block:: console
-
-    $ sudo port install bash-completion
-     
-
-
-   This includes a bash_completion file that needs to be added to the environment.
-
-   .. code-block:: console
-
-    $ $BASH_COMPLETIONS.insert(0, '/opt/local/share/bash-completion/bash_completion')
-
-Note that the `bash completion project page <https://github.com/scop/bash-completion>`_ gives the script to be called as in .../profile.d/bash_completion.sh which will the call the script mentioned above and one in $XDG_CONFIG_HOME . Currently xonsh seems only to be able to read the first script directly.
-
-
-.. include:: dependencies.rst
-
-Customization
-=============
-
-See the `xonsh customization guide <customization.html>`_ for more details on setting up ``xonsh``!
diff --git a/docs/packages.rst b/docs/packages.rst
new file mode 100644
index 0000000000..595a794e33
--- /dev/null
+++ b/docs/packages.rst
@@ -0,0 +1,92 @@
+Via Package Manager
+===================
+
+You can install xonsh using ``conda``, ``pip`` or the package manager for 
+your operating system distribution.
+
+For the fullest interactive user experience, these additional packages should also be installed:
+
+  :prompt-toolkit: for command completion, configurable key bindings and especially multi-line line editing.
+  :pygments: for xonsh and python syntax-specific highlighting
+  :setproctitle: updates process title (in terminal window and process monitor) to match Xonsh arguments.
+
+Installing with these packages is the recommended configuration and is documented first.   
+If you are operating in a specialized or restricted environment, you can install just the xonsh package, as 
+described in `fewer prerequisites`_
+
+
+**conda:**
+
+.. code-block:: console
+
+    $ conda config --add channels conda-forge
+    $ conda install pygments prompt-toolkit setproctitle xonsh
+
+
+**pip:** Typically you will activate a virtual environment and install xonsh there.  This will ensure that you invoke the 
+correct python interpreter and ``pip`` module. 
+
+.. code-block:: console
+
+    $ pip install pygments prompt-toolkit setproctitle xonsh
+
+As a shortcut (for pip only), you can specify all of the above with `extras` syntax:
+
+.. code-block:: console
+
+    $ pip install xonsh[full]
+
+The above ``pip`` commands may have to be spelled ``pip3`` or ``sudo pip3`` if you are not installing in a virtual environment.
+
+**source:** Pip can also install the most recent xonsh source code from the 
+`xonsh project repository <https://github.com/xonsh/xonsh>`_.
+
+.. code-block:: console
+
+    $ pip install pygments prompt-toolkit setproctitle https://github.com/xonsh/xonsh/archive/master.zip
+
+Spelling of ``pip`` command may likewise have to be amended as noted above.
+
+**platform package managers**
+Various operating system distributions have platform-specific package managers which may offer a xonsh package.  
+This may not be  the most current version of xonsh, but it should have been tested for stability on that platform
+by the distribution managers.
+
+
+   +---------------------------+-----------------------------+---------------------+
+   | OS or distribution        |  command                    |   Package(s)        |
+   +===========================+=============================+=====================+
+   | Debian/Ubuntu             | ``$ [sudo] apt install``    |                     |
+   +---------------------------+-----------------------------+    pygments         |
+   | Fedora                    | ``$ [sudo] dnf install``    |    prompt-toolkit   |
+   +---------------------------+-----------------------------+    setproctitle     |
+   | Arch Linux                | ``$ [sudo] pacman -S``      |    xonsh            |
+   +---------------------------+-----------------------------+                     |
+   | OSX                       | ``$ [sudo] brew install``   |                     |
+   +---------------------------+-----------------------------+---------------------+
+
+
+If you run into any problems, please let us know!
+
+Fewer Prerequisites
+--------------------
+
+A design goal of Xonsh is to run in any environment that supports a (supported) Python interpreter, you 
+can install just the ``xonsh`` package (using any package manager).
+
+.. code-block:: console
+  
+  pip install xonsh
+
+When it starts up, if xonsh does not find ``pygments`` or ``setproctitle`` packages, it simply does not colorize 
+or highlight syntax or set process title, respectively.  
+
+If it does not find ``prompt-toolkit`` package, it will 
+use the Python ``readline`` module (which reads configuration  file ``.inputrc`` in a manner compatible with ``GNU readline``).  
+To ensure xonsh uses ``readline`` even if ``prompt-toolkit`` is installed, configure this in your
+``.xonshrc`` file:
+
+.. code-block:: xonsh
+
+    $SHELL_TYPE = 'readline'
+
diff --git a/docs/platform-issues.rst b/docs/platform-issues.rst
new file mode 100644
index 0000000000..d527e26332
--- /dev/null
+++ b/docs/platform-issues.rst
@@ -0,0 +1,227 @@
+Platform-specific tips and tricks
+==================================
+
+Linux
+------
+
+Possible conflicts with Bash
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on how your installation of Bash is configured, Xonsh may have trouble
+loading certain shell modules. If you see errors similar to this
+when launching Xonsh:
+
+.. code-block:: console
+
+    bash: module: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_module'
+    bash: scl: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_scl'
+    bash: module: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_module'
+    bash: scl: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_scl'
+
+...You can correct the problem by unsetting the modules, by adding the following
+lines to your ``~/.bashrc file``:
+
+.. code-block:: console
+
+    unset module
+    unset scl
+
+
+Default Ubuntu .bashrc breaks Foreign Shell Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Xonsh supports importing functions from foreign shells using the
+`ForeignShellFunctionAlias` class, which calls functions as if they were
+aliases. This is implemented by executing a command that sources the file
+containing the function definition and then immediately calls the function with
+any necessary arguments.
+
+The default user `~/.bashrc` file in Ubuntu 15.10 has the following snippet at
+the top, which causes the script to exit immediately if not run interactively.
+
+.. code-block:: bash
+
+    # If not running interactively, don't do anything
+    case $- in
+        *i*) ;;
+          *) return;;
+    esac
+
+This means that any function you have added to the file after this point will be
+registered as a xonsh alias but will fail on execution if the 
+shell is not running interactively. Previous versions of
+Ubuntu have a different test for interactivity at the top of the file that
+yields the same problem.
+
+
+MacOS, OSX
+----------
+
+readline
+^^^^^^^^
+
+[ed note: This recommendation seems to be `out of date <https://pypi.org/project/gnureadline/>`_. 
+It's retained in the current docs in case you have an older version of Python or MacOS.  But if 
+you have Mac platform experience and can clarify, please open an issue or even a PR to correct the documentation.]
+
+On macOS, it is *strongly* recommended to install the ``gnureadline`` library if using the readline shell.  ``gnureadline`` can be installed via pip:
+
+.. code-block:: console
+
+    $ pip3 install gnureadline
+
+Path Helper
+^^^^^^^^^^^
+
+macOS provides a `path helper
+<http://www.softec.lu/site/DevelopersCorner/MasteringThePathHelper>`_,
+which by default configures paths in bash and other POSIX or C  shells. Without
+including these paths, common tools including those installed by Homebrew
+may be unavailable. See ``/etc/profile`` for details on how it is done.
+To ensure the path helper is invoked on xonsh (for all users), add the
+following to ``/etc/xonshrc``::
+
+    source-bash $(/usr/libexec/path_helper -s)
+
+To incorporate the whole functionality of ``/etc/profile``::
+
+    source-bash --seterrprevcmd "" /etc/profile
+
+
+
+Tab completion
+^^^^^^^^^^^^^^
+Xonsh has support for using bash completion files on the shell, to use it you need to install 
+the bash-completion package. 
+The regular bash-completion package uses v1 which mostly works, but `occasionally has rough edges <https://github.com/xonsh/xonsh/issues/2111>`_ so we recommend using bash-completion v2.
+
+Bash completion comes from <https://github.com/scop/bash-completion> which suggests you use a package manager to install it, this manager will also install a new version of bash without affecting  /bin/bash. Xonsh also needs to be told where the bash shell file that builds the completions is, this has to be added to $BASH_COMPLETIONS. The package includes completions for many Unix commands.
+
+Common packaging systems for MacOs include
+
+ -  Homebrew where the bash-completion2 package needs to be installed.
+
+    .. code-block:: console
+
+       $ brew install bash-completion2
+       
+    This will install the bash_completion file in `/usr/local/share/bash-completion/bash_completion` which is in the current xonsh code and so should just work.
+
+ - `MacPorts <https://trac.macports.org/wiki/howto/bash-completion>`_ where the bash-completion port needs to be installed.
+
+   .. code-block:: console
+
+    $ sudo port install bash-completion
+     
+
+
+   This includes a bash_completion file that needs to be added to the environment.
+
+   .. code-block:: console
+
+    $ $BASH_COMPLETIONS.insert(0, '/opt/local/share/bash-completion/bash_completion')
+
+Note that the `bash completion project page <https://github.com/scop/bash-completion>`_ gives the script to be called as in .../profile.d/bash_completion.sh which will the call the script mentioned above and one in $XDG_CONFIG_HOME . Currently xonsh seems only to be able to read the first script directly.
+
+
+
+
+
+Windows
+-------
+
+Windows Terminal
+^^^^^^^^^^^^^^^^
+
+If you are running a supported version of Windows (which is now Windows 10, version 2004 or later), 
+we recommend the Windows Terminal (``wt.exe``) rather than the time-honored ``cmd.exe``.  This provides
+unicode rendering, better ansi terminal compatibility and all the conveniences you expect 
+from the terminal application in other platforms.
+
+You can install it from the `Microsoft Store<https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701>`_ 
+or from `Github<https://github.com/microsoft/terminal>`_.
+
+By default Windows Terminal runs Powershell, but comes with a profile tab that runs `cmd.exe` instead, and you can add one for Xonsh as well.
+
+Nice colors
+^^^^^^^^^^^
+
+The dark red and blue colors are completely unreadable in `cmd.exe`.
+
+.. image:: _static/intensify-colors-on-win-false.png
+   :width: 396 px
+   :alt: intensify-colors-win-false
+   :align: center
+
+Xonsh has some tricks to fix colors. This is controlled by the
+:ref:`$INTENSIFY_COLORS_ON_WIN <intensify_colors_on_win>`
+environment variable which is ``True`` by default. 
+
+
+:ref:`$INTENSIFY_COLORS_ON_WIN <intensify_colors_on_win>` has the following effect:b 
+
+On Windows 10:
+    Windows 10 supports true color in the terminal, so on Windows 10 Xonsh will use
+    a style with hard coded colors instead of the terminal colors.
+
+On older Windows:
+    Xonsh replaces some of the unreadable dark colors with more readable
+    alternatives (e.g. blue becomes cyan).
+
+
+Avoid locking the working directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Python (like other processes on Windows) locks the current working directory so
+it can't be deleted or renamed. ``cmd.exe`` has this behaviour as well, but it
+is quite annoying for a shell. 
+
+The :ref:`free_cwd <free_cwd>` xontrib (add-on) for xonsh solves some of this problem. It
+works by hooking the prompt to reset the current working directory to the root
+drive folder whenever the shell is idle. It only works with the prompt-toolkit
+back-end. To enable that behaviour run the following: 
+
+Add this line to your ``~/.xonshrc`` file to have it always enabled. 
+
+.. code-block:: xonshcon
+
+   >>> xontrib load free_cwd
+
+
+Name space conflicts
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Due to ambiguity with the Python ``dir`` builtin, to list the current directory
+you must explicitly request the ``.``, like this:
+
+.. code-block:: xonshcon
+
+   >>> dir .
+    Volume in drive C is Windows
+    Volume Serial Number is 30E8-8B86
+
+    Directory of C:\Users\snail\xonsh
+
+   2015-05-12  03:04    <DIR>          .
+   2015-05-12  03:04    <DIR>          ..
+   2015-05-01  01:31    <DIR>          xonsh
+                  0 File(s)              0 bytes
+                  3 Dir(s)  11,008,000,000 bytes free
+
+
+
+Many people create a ``d`` alias for the ``dir`` command to save
+typing and avoid the ambiguity altogether:
+
+.. code-block:: xonshcon
+
+   >>> aliases['d'] = ['cmd', '/c', 'dir']
+
+You can add aliases to your ``~/.xonshrc`` to have it always
+available when xonsh starts.
+
+
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index b18af1bd01..67a3eb1dfc 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -3,6 +3,7 @@
 *******************
 Tutorial
 *******************
+
 xonsh is a shell language and command prompt. Unlike other shells, xonsh is
 based on Python, with additional syntax added that makes calling subprocess
 commands, manipulating the environment, and dealing with the file system
diff --git a/docs/windows.rst b/docs/windows.rst
deleted file mode 100644
index 58a6f05b46..0000000000
--- a/docs/windows.rst
+++ /dev/null
@@ -1,183 +0,0 @@
-==========================
-Windows Guide
-==========================
-
-Installation
-================
-
-The easy way
-----------------
-
-The easiest way to install xonsh on windows is through the `Anaconda Python
-Distribution <https://www.anaconda.com/download/>`__ and the conda package manager.
-
-.. note::
-
-    Xonsh is not supported on legacy Python (2.7).
-
-Install xonsh with the following command:
-
-.. code-block:: bat
-
-   > conda config --add channels conda-forge
-   > conda install xonsh
-
-This will install xonsh and all the recommended dependencies. Next, run xonsh:
-
-.. code-block:: bat
-
-   > xonsh
-   snail@home ~ $
-
-
-Install from source
--------------------
-
-To install xonsh from source on Windows, first install `Python v3.4+`_ from
-http://python.org. Remember to select "Add python to PATH" during installation.
-
-Next, install the prompt_toolkit dependency via ``pip``:
-
-.. code-block:: bat
-
-   > pip install prompt-toolkit
-
-Download the latest `xonsh-master.zip`_ from github and unzip it
-to ``xonsh-master``.
-
-Now install xonsh:
-
-.. code-block:: bat
-
-   > cd xonsh-master
-   > pip install .
-
-Next, run xonsh:
-
-.. code-block:: bat
-
-  > xonsh
-  snail@home ~ $
-
-.. _Python v3.4+: https://www.python.org/downloads/windows/
-.. _xonsh-master.zip: https://github.com/xonsh/xonsh/archive/master.zip
-.. _cmder: http://cmder.net/
-.. _conemu: https://conemu.github.io/
-
-
-Tips and Tricks
-================
-
-Nice colors
-----------------------
-
-The dark red and blue colors are completely unreadable in Windows' default
-terminal.
-
-.. image:: _static/intensify-colors-on-win-false.png
-   :width: 396 px
-   :alt: intensify-colors-win-false
-   :align: center
-
-There are ways to `configure the colors`_ of the old terminal, but to give new users the
-best experience Xonsh has some tricks to fix colors. This is controlled by the
-:ref:`$INTENSIFY_COLORS_ON_WIN <intensify_colors_on_win>`
-environment variable which is ``True`` by default. 
-
-.. _configure the colors: https://blogs.msdn.microsoft.com/commandline/2017/08/11/introducing-the-windows-console-colortool/
-
-:ref:`$INTENSIFY_COLORS_ON_WIN <intensify_colors_on_win>` has the following effect:b 
-
-On Windows 10:
-    Windows 10 supports true color in the terminal, so on Windows 10 Xonsh will use
-    a style with hard coded colors instead of the terminal colors.
-
-On older Windows:
-    Xonsh replaces some of the unreadable dark colors with more readable
-    alternatives (e.g. blue becomes cyan).
-
-   
-**The new Windows terminal**
-
-The best option on windows is to use the new `Windows Terminal
-<https://github.com/microsoft/terminal>`__ developed by Microsoft as an open
-source project. The new terminal supports has many nice features including
-Unicode rendering. 
-
-It is highly recommended and can easily be `installed from the Windows Store`_:
-
-
-.. image:: _static/windows_terminal2.png
-   :alt: Unicode support in Windows terminal
-   :align: center
-
-
-.. _installed from the Windows Store: https://blogs.msdn.microsoft.com/commandline/2017/08/11/introducing-the-windows-console-colortool/
-
-
-
-Avoid locking the working directory
------------------------------------
-
-Python (like other processes on Windows) locks the current working directory so
-it can't be deleted or renamed. ``cmd.exe`` has this behaviour as well, but it
-is quite annoying for a shell. 
-
-The :ref:`free_cwd <free_cwd>` xontrib (add-on) for xonsh solves some of this problem. It
-works by hooking the prompt to reset the current working directory to the root
-drive folder whenever the shell is idle. It only works with the prompt-toolkit
-back-end. To enable that behaviour run the following: 
-
-Add this line to your ``~/.xonshrc`` file to have it always enabled. 
-
-.. code-block:: xonshcon
-
-   >>> xontrib load free_cwd
-
-
-Name space conflicts
---------------------
-
-Due to ambiguity with the Python ``dir`` builtin, to list the current directory
-via the ``cmd.exe`` builtin you must explicitly request the ``.``, like this:
-
-.. code-block:: xonshcon
-
-   >>> dir .
-    Volume in drive C is Windows
-    Volume Serial Number is 30E8-8B86
-
-    Directory of C:\Users\snail\xonsh
-
-   2015-05-12  03:04    <DIR>          .
-   2015-05-12  03:04    <DIR>          ..
-   2015-05-01  01:31    <DIR>          xonsh
-                  0 File(s)              0 bytes
-                  3 Dir(s)  11,008,000,000 bytes free
-
-
-
-Many people create a ``d`` alias for the ``dir`` command to save
-typing and avoid the ambiguity altogether:
-
-.. code-block:: xonshcon
-
-   >>> aliases['d'] = ['cmd', '/c', 'dir']
-
-You can add aliases to your ``~/.xonshrc`` to have it always
-available when xonsh starts.
-
-
-
-Unicode support for Windows
-----------------------------
-
-Python's utf-8 unicode is not compatible with the default console "conhost" on Windows.
-
-Luckily, Microsoft is developing a new `Windows terminal <https://github.com/microsoft/terminal>`__ as an open source project. The new terminal supports all the nice features of 
-that you find in linux terminals. It is highly recommended and can easily be `installed from the Windows Store`_:
-
-.. image:: _static/windows_terminal.png
-   :alt: Unicode support in Windows terminal
-   :align: center
-
diff --git a/docs/xonshrc.rst b/docs/xonshrc.rst
index d361db3473..bbf44668b7 100644
--- a/docs/xonshrc.rst
+++ b/docs/xonshrc.rst
@@ -1,13 +1,160 @@
 Run Control File
 =========================
-Xonsh allows you to have run control files to customize your shell behavior.  These are called ``xonshrc`` files.
+Xonsh allows you to customize your shell behavior with run control files, called "xonshrc" files.  
+These files are written in the xonsh language (a superset of Python) and are executed exactly once at startup.   
+The control file usually contains:
 
-The system-wide ``xonshrc`` file controls options that are applied to all users of Xonsh on a given system.  You can create this file in ``/etc/xonshrc`` for Linux and OSX and in ``%ALLUSERSPROFILE%\xonsh\xonshrc`` on Windows.
+* Assignment statements setting `environment variables <envvars.html>`_.  This includes standard OS environment variables that affect other programs and many that Xonsh uses for itself.
+* ``xonfig`` commands to load selected add-ins ("`xontribs<tutorial_xontrib.html#loading-xontribs>`")
+* Xonsh function defintions
+* `Alias definitions <aliases.html>`_, many of which invoke the above functions with specified arguments.
 
-Xonsh also allows you to have a run control file in your home directory. It can either be directly in the home directory at ``~/.xonshrc`` or for XDG compliance at ``~/.config/rc.xsh``. The options set in the local ``xonshrc`` only apply to the current user and will override any conflicting settings set in the system-wide control file.
+The system-wide ``xonshrc`` file controls options that are applied to all users of Xonsh on a given system.  
+You can create this file in ``/etc/xonshrc`` for Linux and OSX and in ``%ALLUSERSPROFILE%\xonsh\xonshrc`` on Windows.
 
-These files are written in the xonsh language, of course. They are executed exactly once
-at startup. The following is a real-world example of such a file.
+Xonsh also allows a per-user  run control file in your home directory, either
+directly in the home directory at ``~/.xonshrc`` or, for XDG compliance, at ``~/.config/rc.xsh``. 
+The options set per user override settings in the system-wide control file.
+
+Xonsh provides 2 wizards to create your own "xonshrc".  ``xonfig web`` provides basic settings, and ``xonfig wizard``
+steps you through all the available options.
+
+Xonfig web
+-----------
+
+This helps you choose a color theme, customized prompt and add-in packages ("xontribs").  It 
+initializes your personal run control file (usually at ``~/.xonshrc``).  To invoke it (from a xonsh prompt):
+
+.. code-block:: xonshcon
+  
+  >>> xonfig web
+  Web config started at 'http://localhost:8421'. Hit Crtl+C to stop.
+  127.0.0.1 - - [23/Aug/2020 15:04:39] "GET / HTTP/1.1" 200 -
+
+This will open your default browser on a page served from a local server.  You can exit the server by typing ``Ctrl+c`` at any time.
+
+The page has:
+ 
+:Colors: shows the  color themes built into Xonsh.  
+  Simply click on a sample to select it.  Although color names are standardized across various terminal applications, 
+  their actual appearance is not and do vary widely.  Seeing is believing! 
+:Prompts: shows various sample prompts.  It is recommended to select one but to then edit 
+  the ``xonshrc`` file to further refine your prompt.
+:Xontribs: are community-contributed add-ins often used to enhance command completion and line editing, 
+  but can affect any aspect of Xonsh behavior.  
+  Choose one or more to suit your needs but note that they will require installation of additional
+  packages.  You can extend Xonsh by `writing your own xontrib <tutorial_xontrib.html>`_, and are invited/urged to do so!
+:Save: Click to write the configuration choices to your `~/.xonshrc`. This will add a few tagged lines to your run control file, but will not 
+  overwrite it completely, so you can run `xonfig web` at any time.
+
+xonfig wizard
+--------------
+
+This imports settings and tools you have defined in your existing (ordinary) shell such as ``bash``.  
+It also walks you through setting all known environment variables and xontribs 
+in a question-and-answer format:
+
+.. code-block:: xonshcon
+
+  $ xonfig wizard
+
+            Welcome to the xonsh configuration wizard!
+            ------------------------------------------
+  This will present a guided tour through setting up the xonsh static
+  config file. Xonsh will automatically ask you if you want to run this
+  wizard if the configuration file does not exist. However, you can
+  always rerun this wizard with the xonfig command:
+
+      $ xonfig wizard
+
+  This wizard will load an existing configuration, if it is available.
+  Also never fear when this wizard saves its results! It will create
+  a backup of any existing configuration automatically.
+
+  This wizard has two main phases: foreign shell setup and environment
+  variable setup. Each phase may be skipped in its entirety.
+
+  For the configuration to take effect, you will need to restart xonsh.
+
+  '`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'``-.,_,.-*'
+
+  To exit the wizard at any time, press Ctrl-C.
+
+
+  '`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'
+
+                        Foreign Shell Setup
+                        -------------------
+  The xonsh shell has the ability to interface with foreign shells such
+  as Bash, or zsh (fish not yet implemented).
+
+  For configuration, this means that xonsh can load the environment,
+  aliases, and functions specified in the config files of these shells.
+  Naturally, these shells must be available on the system to work.
+  Being able to share configuration (and source) from foreign shells
+  makes it easier to transition to and from xonsh.
+
+  Add a new foreign shell, yes or no [default: no]? yes
+  shell name (e.g. bash): bash
+  interactive shell [bool, default=True]:
+  login shell [bool, default=False]:
+  env command [str, default='env']:
+  alias command [str, default='alias']:
+  extra command line arguments [list of str, default=[]]:
+  safely handle exceptions [bool, default=True]:
+  pre-command [str, default='']:
+  post-command [str, default='']:
+  foreign function command [str, default=None]:
+  source command [str, default=None]: source
+  Foreign shell added.
+
+  Add a new foreign shell, yes or no [default: no]? no
+
+  '`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'``-.,_,.-*'
+
+                    Environment Variable Setup
+                    --------------------------
+  The xonsh shell also allows you to setup environment variables from
+  the static configuration file. Any variables set in this way are
+  superseded by the definitions in the xonshrc or on the command line.
+  Still, setting environment variables in this way can help define
+  options that are global to the system or user.
+
+  The following lists the environment variable name, its documentation,
+  the default value, and the current value. The default and current
+  values are presented as pretty repr strings of their Python types.
+
+  Note: Simply hitting enter for any environment variable
+  will accept the default value for that entry.
+
+  Would you like to set env vars now, yes or no [default: no]? yes
+
+  $ALLUSERSPROFILE
+
+  default value:
+  current value: 'C:\\ProgramData'
+  >>>
+
+  $APPDATA
+
+  default value:
+  current value: 'C:\\Users\\bobhy\\AppData\\Roaming'
+  >>>
+
+  $AUTO_CD
+  Flag to enable changing to a directory by entering the dirname or
+  full path only (without the cd command).
+  default value: False
+  current value: False
+  >>>
+
+  . . .
+
+
+Real world sample xonshrc
+-------------------------
+
+The following is a real-world example of such a file.
 
 :download:`Download xonshrc <xonshrc.xsh>`
 
@@ -16,12 +163,13 @@ at startup. The following is a real-world example of such a file.
 
 
 Snippets for xonshrc
-=========================
-The following are usefull snippets and code that tweaks and adjust xonsh in various ways.
+--------------------
+
+The following are useful snippets and code that tweaks and adjust xonsh in various ways.
 If you have any useful tricks, feel free to share them.
 
 Adjust how git branch label behaves
--------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Xonsh adds a colored branch name to the prompt when working with git or hg repositories.
 This behavior can be controlled with the ``$PROMPT`` environment variable. See how to `customize the prompt`_ .
 The branch name changes color if the work dir is dirty or not. This is controlled by the ``{branch_color}`` formatter string.
@@ -37,11 +185,11 @@ The following snippet reimplements the formatter also to include untracked files
                                                    else '{BOLD_INTENSE_GREEN}')
 
 
-.. _customize the prompt: http://xon.sh/tutorial.html#customizing-the-prompt
+.. _customize the prompt: tutorial.html#customizing-the-prompt
 
 
 Get better colors from the ``ls`` command
-----------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The colors of the ``ls`` command may be hard to read in a dark terminal. If so, this is an excellent addition to the xonshrc file.
 
 .. code-block:: xonshcon
@@ -49,8 +197,9 @@ The colors of the ``ls`` command may be hard to read in a dark terminal. If so,
     >>> $LS_COLORS='rs=0:di=01;36:ln=01;36:mh=00:pi=40;33:so=01;35:do=01;35:bd=40;33;01:cd=40;33;01:or=40;31;01:su=37;41:sg=30;43:ca=30;41:tw=30;42:ow=34;42:st=37;44:ex=01;32:'
     
 Make JSON data directly pastable
---------------------------------
-With the following snippet, xonsh will understand JSON data such as ``{ "name": "Tyler", "active": false, "age": null }``. Note that, though practical, this is rather hacky and might break other functionality. Use at your own risk.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+With the following snippet, xonsh will understand JSON data such as ``{ "name": "Tyler", "active": false, "age": null }``. 
+Note that, though practical, this is rather hacky and might break other functionality. Use at your own risk.
 
 .. code-block:: xonshcon
 
@@ -60,7 +209,7 @@ With the following snippet, xonsh will understand JSON data such as ``{ "name":
     >>> builtins.null = None
     
 Display different date information every 10th time
----------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 For a compact shell prompts, some people prefer a very condensed time format. But when you have a lengthy shell session you might want the date to show up in your logs every now and then...
 
 .. code-block:: xonshcon
@@ -77,7 +226,7 @@ For a compact shell prompts, some people prefer a very condensed time format. Bu
     >>> $PROMPT_FIELDS['shelldate'] = get_shelldate
     
 Use the Nix Package manager with Xonsh
---------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 To users of the `Nix Package Manager <https://www.nixos.org/>`_ these few lines might be life-savers:
 
 .. code-block:: xonshcon
diff --git a/news/is_3622.rst b/news/is_3622.rst
new file mode 100644
index 0000000000..3c939e8ef7
--- /dev/null
+++ b/news/is_3622.rst
@@ -0,0 +1,25 @@
+**Added:**
+
+* Setup extras tag '[full]' to install prompt-toolkit and pygments in one fell swoop.
+  Full feature install can be ``pip install xonsh[full]``.
+
+**Changed:**
+
+* Rewrote Installation and Configuration sections of Getting Started doc 
+  to clarify install from packages, and generally improve flow.
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* RST code-block:: xonshcon now works.
+
+**Security:**
+
+* <news item>
diff --git a/setup.cfg b/setup.cfg
index 6d97666733..ea607a14aa 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -18,7 +18,7 @@ exclude =
     .vscode/,
     feedstock,
     rever,
-    .venv,
+    .venv*/,
     # remove later
     pygments_cache.py
 # lint nits that are acceptable in Xonsh project:
diff --git a/setup.py b/setup.py
index 6861e72172..a2e2dc535a 100755
--- a/setup.py
+++ b/setup.py
@@ -412,6 +412,7 @@ def main():
         "linux": ["distro"],
         "proctitle": ["setproctitle"],
         "zipapp": ['importlib_resources; python_version < "3.7"'],
+        "full" : ["ptk", "pygments", "distro"]
     }
     skw["python_requires"] = ">=3.6"
     setup(**skw)


Code review comments:
diff_hunk: @@ -0,0 +1,227 @@
+Platform-specific tips and tricks
+==================================
+
+Linux
+------
+
+Possible conflicts with Bash
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on how your installation of Bash is configured, Xonsh may have trouble
+loading certain shell modules. If you see errors similar to this
+when launching Xonsh:
+
+.. code-block:: console
+
+    bash: module: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_module'
+    bash: scl: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_scl'
+    bash: module: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_module'
+    bash: scl: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_scl'
+
+...You can correct the problem by unsetting the modules, by adding the following
+lines to your ``~/.bashrc file``:
+
+.. code-block:: console
+
+    unset module
+    unset scl
+
+
+Default Ubuntu .bashrc breaks Foreign Shell Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Xonsh supports importing functions from foreign shells using the
+`ForeignShellFunctionAlias` class, which calls functions as if they were
+aliases. This is implemented by executing a command that sources the file
+containing the function definition and then immediately calls the function with
+any necessary arguments.
+
+The default user `~/.bashrc` file in Ubuntu 15.10 has the following snippet at
+the top, which causes the script to exit immediately if not run interactively.
+
+.. code-block:: bash
+
+    # If not running interactively, don't do anything
+    case $- in
+        *i*) ;;
+          *) return;;
+    esac
+
+This means that any function you have added to the file after this point will be
+registered as a xonsh alias but will fail on execution if the 
+shell is not running interactively. Previous versions of
+Ubuntu have a different test for interactivity at the top of the file that
+yields the same problem.
+
+
+MacOS, OSX
+----------
+
+readline
+^^^^^^^^
+
+[ed note: This recommendation seems to be `out of date <https://pypi.org/project/gnureadline/>`_. 
+It's retained in the current docs in case you have an older version of Python or MacOS.  But if 
+you have Mac platform experience and can clarify, please open an issue or even a PR to correct the documentation.]
+
+On macOS, it is *strongly* recommended to install the ``gnureadline`` library if using the readline shell.  ``gnureadline`` can be installed via pip:
+
+.. code-block:: console
+
+    $ pip3 install gnureadline
+
+Path Helper
+^^^^^^^^^^^
+
+macOS provides a `path helper
+<http://www.softec.lu/site/DevelopersCorner/MasteringThePathHelper>`_,
+which by default configures paths in bash and other POSIX or C  shells. Without
+including these paths, common tools including those installed by Homebrew
+may be unavailable. See ``/etc/profile`` for details on how it is done.
+To ensure the path helper is invoked on xonsh (for all users), add the
+following to ``/etc/xonshrc``::
+
+    source-bash $(/usr/libexec/path_helper -s)
+
+To incorporate the whole functionality of ``/etc/profile``::
+
+    source-bash --seterrprevcmd "" /etc/profile
+
+
+
+Tab completion
+^^^^^^^^^^^^^^
+Xonsh has support for using bash completion files on the shell, to use it you need to install 
+the bash-completion package. 
+The regular bash-completion package uses v1 which mostly works, but `occasionally has rough edges <https://github.com/xonsh/xonsh/issues/2111>`_ so we recommend using bash-completion v2.
+
+Bash completion comes from <https://github.com/scop/bash-completion> which suggests you use a package manager to install it, this manager will also install a new version of bash without affecting  /bin/bash. Xonsh also needs to be told where the bash shell file that builds the completions is, this has to be added to $BASH_COMPLETIONS. The package includes completions for many Unix commands.
+
+Common packaging systems for MacOs include
path: docs/platform-issues.rst
text: @user1:
consistent spelling of macOS

diff_hunk: @@ -0,0 +1,92 @@
+Via Package Manager
+===================
+
+You can install xonsh using ``conda``, ``pip`` or the package manager for 
+your operating system distribution.
+
+For the fullest interactive user experience, these additional packages should also be installed:
+
+  :prompt-toolkit: for command completion, configurable key bindings and especially multi-line line editing.
+  :pygments: for xonsh and python syntax-specific highlighting
+  :setproctitle: updates process title (in terminal window and process monitor) to match Xonsh arguments.
+
+Installing with these packages is the recommended configuration and is documented first.   
+If you are operating in a specialized or restricted environment, you can install just the xonsh package, as 
+described in `fewer prerequisites`_
+
+
+**conda:**
+
+.. code-block:: console
+
+    $ conda config --add channels conda-forge
+    $ conda install pygments prompt-toolkit setproctitle xonsh
path: docs/packages.rst
text: @user1:
I think the conda-forge package includes those as deps, so this just needs to be `conda install xonsh`

diff_hunk: @@ -0,0 +1,227 @@
+Platform-specific tips and tricks
+==================================
+
+Linux
+------
+
+Possible conflicts with Bash
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on how your installation of Bash is configured, Xonsh may have trouble
+loading certain shell modules. If you see errors similar to this
+when launching Xonsh:
+
+.. code-block:: console
+
+    bash: module: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_module'
+    bash: scl: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_scl'
+    bash: module: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_module'
+    bash: scl: line 1: syntax error: unexpected end of file
+    bash: error importing function definition for 'BASH_FUNC_scl'
+
+...You can correct the problem by unsetting the modules, by adding the following
+lines to your ``~/.bashrc file``:
+
+.. code-block:: console
+
+    unset module
+    unset scl
+
+
+Default Ubuntu .bashrc breaks Foreign Shell Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Xonsh supports importing functions from foreign shells using the
+`ForeignShellFunctionAlias` class, which calls functions as if they were
+aliases. This is implemented by executing a command that sources the file
+containing the function definition and then immediately calls the function with
+any necessary arguments.
+
+The default user `~/.bashrc` file in Ubuntu 15.10 has the following snippet at
path: docs/platform-issues.rst
text: @user1:
double backticks

diff_hunk: @@ -1,13 +1,160 @@
 Run Control File
 =========================
-Xonsh allows you to have run control files to customize your shell behavior.  These are called ``xonshrc`` files.
+Xonsh allows you to customize your shell behavior with run control files, called "xonshrc" files.  
+These files are written in the xonsh language (a superset of Python) and are executed exactly once at startup.   
+The control file usually contains:
 
-The system-wide ``xonshrc`` file controls options that are applied to all users of Xonsh on a given system.  You can create this file in ``/etc/xonshrc`` for Linux and OSX and in ``%ALLUSERSPROFILE%\xonsh\xonshrc`` on Windows.
+* Assignment statements setting `environment variables <envvars.html>`_.  This includes standard OS environment variables that affect other programs and many that Xonsh uses for itself.
+* ``xonfig`` commands to load selected add-ins ("`xontribs<tutorial_xontrib.html#loading-xontribs>`")
+* Xonsh function defintions
+* `Alias definitions <aliases.html>`_, many of which invoke the above functions with specified arguments.
 
-Xonsh also allows you to have a run control file in your home directory. It can either be directly in the home directory at ``~/.xonshrc`` or for XDG compliance at ``~/.config/rc.xsh``. The options set in the local ``xonshrc`` only apply to the current user and will override any conflicting settings set in the system-wide control file.
+The system-wide ``xonshrc`` file controls options that are applied to all users of Xonsh on a given system.  
+You can create this file in ``/etc/xonshrc`` for Linux and OSX and in ``%ALLUSERSPROFILE%\xonsh\xonshrc`` on Windows.
 
-These files are written in the xonsh language, of course. They are executed exactly once
-at startup. The following is a real-world example of such a file.
+Xonsh also allows a per-user  run control file in your home directory, either
+directly in the home directory at ``~/.xonshrc`` or, for XDG compliance, at ``~/.config/rc.xsh``. 
+The options set per user override settings in the system-wide control file.
+
+Xonsh provides 2 wizards to create your own "xonshrc".  ``xonfig web`` provides basic settings, and ``xonfig wizard``
+steps you through all the available options.
+
+Xonfig web
path: docs/xonshrc.rst
text: @user1:
lowercase `x` to be consistent with heading below

diff_hunk: @@ -0,0 +1,4 @@
+Xonsh kernel for Jupyter
+========================
+
+[placeholder]
path: docs/jupyter.rst
text: @user1:
This should be filled out or removed