mirror of
https://github.com/xonsh/xonsh.git
synced 2025-03-04 08:24:40 +01:00
More getting started reorg
This commit is contained in:
Bob Hyman
parent
a67df4fd5f
commit
59bb6b3b88
10 changed files with 211 additions and 134 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>`_.
|
||||
|
|
|
|||
BIN
docs/do_sphinx.ps1
Normal file
BIN
docs/do_sphinx.ps1
Normal file
Binary file not shown.
|
|
@ -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``.
|
||||
|
|
|
|||
|
|
@ -1,20 +1,45 @@
|
|||
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
.. include:: dependencies.rst
|
||||
Installation and Configuration
|
||||
==============================
|
||||
|
||||
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
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
Xonsh uses a startup configuration file and provides a configuration wizard to help you set this up.
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:maxdepth: 2
|
||||
|
||||
xonshrc
|
||||
customization
|
||||
|
|
|
|||
|
|
@ -1,86 +0,0 @@
|
|||
Typical Interactive Installation
|
||||
================================
|
||||
|
||||
For the full Xonsh experience, with colorized syntax and multi-line command editing, you must
|
||||
explicitly install the prerequisite packages before installing xonsh.
|
||||
Xonsh will check for these packages at startup and use
|
||||
them if present, but the installation of Xonsh in any package manager will not automatically install them.
|
||||
|
||||
You can install xonsh using ``conda``, ``pip``, or from source.
|
||||
|
||||
**conda:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ conda config --add channels conda-forge
|
||||
# For prerequisites
|
||||
$ conda install pygments prompt-toolkit setproctitle
|
||||
$ 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
|
||||
|
||||
# For prerequisites
|
||||
$ pip install pygments prompt-toolkit setproctitle
|
||||
$ pip install xonsh
|
||||
|
||||
The above ``pip`` command may have to be spelled ``pip3`` or ``sudo pip3`` if you are not installing in a virtual environment.
|
||||
|
||||
**source:** The most recent xonsh source code from the
|
||||
`xonsh project repository <https://github.com/xonsh/xonsh>`_.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# For prerequisites
|
||||
$ pip install pygments prompt-toolkit setproctitle
|
||||
$ pip install https://github.com/xonsh/xonsh/archive/master.zip
|
||||
|
||||
Spelling of ``pip`` command in this example may 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 | command | Prerequesite package(s) |
|
||||
+--------------+-----------------+----------------------------------+
|
||||
| distribution | | Xonsh package |
|
||||
+==============+=================+==================================+
|
||||
| Debian/Ubuntu | ``$ [sudo] apt install`` | :Prerequisites: |
|
||||
+--------------+---------------------------+ pygments |
|
||||
| Fedora | ``$ [sudo] dnf install`` | prompt-toolkit |
|
||||
+--------------+----------------------------+ setproctitle |
|
||||
| Arch Linux | ``$ [sudo] pacman -S`` | |
|
||||
+--------------+----------------------------+ :Xonsh: |
|
||||
| OSX | ``$ [sudo] brew install`` | xonsh |
|
||||
+--------------+-----------------+----------------------------------+
|
||||
|
||||
|
||||
If you run into any problems, please let us know!
|
||||
|
||||
.. include:: dependencies.rst
|
||||
|
||||
Fewer Prerequisites
|
||||
-------------------------
|
||||
|
||||
A design goal of Xonsh is to run in any environment that supports a (supported) Python interpreter, so you do not
|
||||
have to install any of the optional prerequisites.
|
||||
|
||||
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``).
|
||||
|
||||
|
||||
Customization
|
||||
-------------
|
||||
|
||||
See the `xonsh customization guide <customization.html>`_ for more details on setting up ``xonsh``!
|
||||
|
||||
|
||||
92
docs/packages.rst
Normal file
92
docs/packages.rst
Normal file
|
|
@ -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'
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -2,22 +2,58 @@ Run Control File
|
|||
=========================
|
||||
Xonsh allows you to have run control files to customize your shell behavior. These are called ``xonshrc`` files.
|
||||
|
||||
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.
|
||||
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 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
These files are written in the xonsh language (a superset of Python). They are executed exactly once at startup.
|
||||
The control file usually contains:
|
||||
|
||||
* Assignment statements setting `environment variables <envvars.html>`_. This includes standard OS environment variables that affect other programs and many that Xonsh uses for itself.
|
||||
* Xonsh function defintions
|
||||
* `Alias definitions <aliases.html>`_, many of which invoke the above functions with specified arguments.
|
||||
|
||||
The following is a real-world example of such a file.
|
||||
|
||||
:download:`Download xonshrc <xonshrc.xsh>`
|
||||
|
||||
.. include:: xonshrc.xsh
|
||||
:code: xonsh
|
||||
|
||||
Xonfig web
|
||||
-----------
|
||||
|
||||
Xonsh provides a configuration wizard which 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 run control 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.
|
||||
|
||||
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
|
||||
|
|
@ -37,7 +73,7 @@ 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
|
||||
|
|
@ -50,7 +86,8 @@ The colors of the ``ls`` command may be hard to read in a dark terminal. If so,
|
|||
|
||||
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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue