mirror of
https://github.com/xonsh/xonsh.git
synced 2025-03-04 08:24:40 +01:00
Doc updates per review
This commit is contained in:
Bob Hyman
parent
92ee51a81e
commit
6f549ca6c3
5 changed files with 142 additions and 106 deletions
|
|
@ -4,7 +4,7 @@ Installation
|
|||
|
||||
Prerequisites
|
||||
-------------
|
||||
* python, V3.6 or later.
|
||||
* 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.
|
||||
|
|
@ -20,16 +20,6 @@ Xonsh can be installed via package manager, via appimage or just run from a pre-
|
|||
packages
|
||||
appimage
|
||||
containers
|
||||
|
||||
|
||||
Installation in specialized environments
|
||||
----------------------------------------
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:maxdepth: 2
|
||||
|
||||
jupyter
|
||||
editors
|
||||
|
||||
Configuration and Customization
|
||||
|
|
|
|||
|
|
@ -1,4 +1,11 @@
|
|||
Xonsh kernel for Jupyter
|
||||
========================
|
||||
|
||||
[placeholder]
|
||||
Xonsh provides a kernel for Jupyter Notebook and Lab so you can execute xonsh commands in a notbook cell without any additional magic.
|
||||
|
||||
Installation
|
||||
-------------
|
||||
|
||||
[ed note: this is a stub and the topic is excluded from docs
|
||||
till I or someone can get a consistent install procedure to work!]
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ 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
|
||||
: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.
|
||||
|
|
@ -20,22 +20,22 @@ described in `fewer prerequisites`_
|
|||
.. code-block:: console
|
||||
|
||||
$ conda config --add channels conda-forge
|
||||
$ conda install pygments prompt-toolkit setproctitle xonsh
|
||||
$ conda install 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:
|
||||
correct Python interpreter and ``pip`` module.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install xonsh[full]
|
||||
|
||||
This uses the pip 'extras' syntax, and is equivalent to:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install pygments prompt-toolkit setproctitle xonsh
|
||||
|
||||
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
|
||||
|
|
@ -75,8 +75,8 @@ A design goal of Xonsh is to run in any environment that supports a (supported)
|
|||
can install just the ``xonsh`` package (using any package manager).
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install xonsh
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ 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 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
|
||||
|
|
@ -65,7 +65,7 @@ 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
|
||||
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:
|
||||
|
|
@ -83,11 +83,15 @@ 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``::
|
||||
following to ``/etc/xonshrc``:
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
source-bash $(/usr/libexec/path_helper -s)
|
||||
|
||||
To incorporate the whole functionality of ``/etc/profile``::
|
||||
To incorporate the whole functionality of ``/etc/profile``:
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
source-bash --seterrprevcmd "" /etc/profile
|
||||
|
||||
|
|
@ -101,7 +105,7 @@ The regular bash-completion package uses v1 which mostly works, but `occasionall
|
|||
|
||||
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
|
||||
Common packaging systems for macOS include
|
||||
|
||||
- Homebrew where the bash-completion2 package needs to be installed.
|
||||
|
||||
|
|
@ -128,9 +132,6 @@ Common packaging systems for MacOs include
|
|||
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
|
||||
-------
|
||||
|
||||
|
|
@ -142,10 +143,48 @@ we recommend the Windows Terminal (``wt.exe``) rather than the time-honored ``cm
|
|||
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>`_.
|
||||
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 you can add a profile tab to run Xonsh and even configure it
|
||||
to open automatically in xonsh. Here is a sample settings.json:
|
||||
|
||||
.. code-block::
|
||||
|
||||
{
|
||||
"$schema": "https://aka.ms/terminal-profiles-schema",
|
||||
|
||||
"defaultProfile": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
|
||||
|
||||
// To learn more about global settings, visit https://aka.ms/terminal-global-settings
|
||||
// To learn more about profiles, visit https://aka.ms/terminal-profile-settings
|
||||
"profiles":
|
||||
{
|
||||
"defaults":
|
||||
{
|
||||
// Put settings here that you want to apply to all profiles.
|
||||
},
|
||||
"list":
|
||||
[
|
||||
{
|
||||
// Guid from https://guidgen.com
|
||||
"guid": "{02639f1c-9437-4b34-a383-2df49b5ed5c5}",
|
||||
"name": "Xonsh",
|
||||
"commandline": "c:\\users\\bobhy\\src\\xonsh\\.venv\\scripts\\xonsh.exe",
|
||||
"hidden": false
|
||||
},
|
||||
{
|
||||
// Make changes here to the powershell.exe profile.
|
||||
"guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
|
||||
"name": "Windows PowerShell",
|
||||
"commandline": "powershell.exe",
|
||||
"hidden": false
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
. . .
|
||||
|
||||
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
|
||||
^^^^^^^^^^^
|
||||
|
|
|
|||
144
docs/xonshrc.rst
144
docs/xonshrc.rst
|
|
@ -12,14 +12,14 @@ 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.
|
||||
|
||||
Xonsh also allows a per-user run control file in your home directory, either
|
||||
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
|
||||
xonfig web
|
||||
-----------
|
||||
|
||||
This helps you choose a color theme, customized prompt and add-in packages ("xontribs"). It
|
||||
|
|
@ -44,7 +44,7 @@ The page has:
|
|||
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
|
||||
: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
|
||||
|
|
@ -56,99 +56,99 @@ in a question-and-answer format:
|
|||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
$ xonfig wizard
|
||||
$ 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:
|
||||
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
|
||||
$ 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 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.
|
||||
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.
|
||||
For the configuration to take effect, you will need to restart xonsh.
|
||||
|
||||
'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'``-.,_,.-*'
|
||||
'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'``-.,_,.-*'
|
||||
|
||||
To exit the wizard at any time, press Ctrl-C.
|
||||
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).
|
||||
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.
|
||||
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]? 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
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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
|
||||
Would you like to set env vars now, yes or no [default: no]? yes
|
||||
|
||||
$ALLUSERSPROFILE
|
||||
$ALLUSERSPROFILE
|
||||
|
||||
default value:
|
||||
current value: 'C:\\ProgramData'
|
||||
>>>
|
||||
default value:
|
||||
current value: 'C:\\ProgramData'
|
||||
>>>
|
||||
|
||||
$APPDATA
|
||||
$APPDATA
|
||||
|
||||
default value:
|
||||
current value: 'C:\\Users\\bobhy\\AppData\\Roaming'
|
||||
>>>
|
||||
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
|
||||
>>>
|
||||
$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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue