--- a/docs/README.rst Fri Apr 19 17:59:43 2019 +0200
+++ b/docs/README.rst Sat Apr 20 19:01:54 2019 +0200
@@ -2,109 +2,87 @@
README for the eric6 IDE
========================
+0. What is eric6?
+-----------------
+eric6 is a full featured Python editor and IDE, written in Python. It is based
+on the cross platform Qt UI toolkit, integrating the highly flexible Scintilla
+editor control. It is designed to be usable as everdays' quick and dirty editor
+as well as being usable as a professional project management tool integrating
+many advanced features Python offers the professional coder. eric6 includes a
+plug-in system, which allows easy extension of the IDE functionality with
+plug-ins downloadable from the net. For more details see
+<https://eric-ide.python-projects.org>.
+
1. Installation
---------------
-Installing eric6 is a simple process. Just execute the ``install.py`` script
-(type ``python install.py -h`` for some help). Please note that the
-installation has to be performed using the administrators account (i.e. root
-on linux). This installs a wrapper script called eric6 in the standard
-executable directory.
+Installing eric6 is a simple process. There are various methods available.
+Please choose the one best suited to your needs and skills. eric6 may be used
+with any combination of Python 3 or 2, Qt5 or Qt4 and PyQt5 or PyQt4. However,
+the recommended combination is **Python3** and **PyQt5**.
+
+1.1 Create a Python virtual environment for eric6
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is recommended to install eric6 into a Python virtual environment in order
+to keep your Python distribution clean. In order to do that create it by
+entering the following command in a terminal window::
+
+ python3 -m venv eric6_venv
+
+Replace ``eric6_venv`` with the desired path to the directory for the virtual
+environment. All further instructions will assume this environment name.
+
+1.2a Variant 1: Installation via the "install.py" script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This method results in the most complete install on all supported platforms.
+After extracting the eric6 distribution archive just execute the following
+command in a terminal window::
+
+ ~/eric6_venv/bin/python3 install.py
+
+Change the path to the Python executable appropriately. The installation script
+will check for all pre-requisites and will ask for confirmation to install
+them. If the installation process needs tuning type
+``~/eric6_venv/bin/python3 install.py --help`` for some help.
If you want to uninstall the package just execute the ``uninstall.py`` script.
This gets rid of all installed files. In this case please send an email to the
below mentioned address and tell me your reason. This might give me a hint on
how to improve eric6.
-eric6 may be used with any combination of Python 3 or 2, Qt5 or Qt4 and
-PyQt5 or PyQt4. If the required packages (Qt5/4, QScintilla2, sip and PyQt5/4)
-are not installed, please get them and install them in the following order
-(order is important).
-
-1. Install Qt5 (from The Qt Company)
-
-2. Build and install QScintilla2 (from Riverbank Computing)
+1.2b Variant 2: Installation via the Python Package Index PyPI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This method is the easiest one but does not create a macOS® Application. Enter
+the following command in a terminal window::
-3. Build and install sip (from Riverbank Computing)
-
-4. Build and install PyQt5 (from Riverbank Computing)
-
-5. Build and install QScintilla2 Python bindings
- (part of the QScintilla2 package)
-
-6. Install eric6
-
-If you want to use the interfaces to other supported software packages, you may
-install them in any order and at any time.
+ ~/eric6_venv/bin/python3 -m pip install eric6
-Please note, that the QScintilla2 Python bindings have to be rebuild, if
-the PyQt5 package gets updated. If this step is omitted, a bunch of strange
-errors will occur.
-
-1.1 Installation on Windows®
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-**Note:** This section is valid for PyQt4 and PyQt5 before 5.7.0.
-
-Installing eric6 on Windows® is even easier. Just download the PyQt5
-installer from Riverbank Computing and use it to install PyQt5. This includes
-all the required Qt5 libraries and tools as well as QScintilla. Once
-this installation is completed install eric6. That's all.
+Once the installation is finished navigate to the executable directory of
+the Python virtual environment and execute the ``eric6_post_install`` script.
+This will create application menu entries on Linux and desktop and start menu
+entries on Windows® platforms.
-1.2 Installation using PyQt5 wheels
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-**Note:** This section is valid for PyQt5 5.7.0 or newer.
+1.3 Installation of Qt Tools via Qt online installer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In order to get the most out of eric6 it is recommended to install the Qt Tools
+like ``Qt Designer`` or ``Qt Linguist``. The recommended way is this.
-Installing eric6 and its pre-requisites is even easier using the PyQt5 Python
-wheels. In order to have access to the suite of Qt tools and documentation it
-is recommended to install the Qt development environment. These tools are not
-part of the PyQt5 wheels. Users of the Windows® operating system may use the
-'pyqt5-tools' wheel available via the Python Package Index (PyPI) as of
-2017-05-12.
-
-1.2.1 Installation of Qt Tools via Qt online installer
-======================================================
1. Download the Qt online installer from the Qt download site.
2. Install Qt by executing the installer.
-1.2.2 Installation of Qt Tools via PyPI
-=======================================
-1. Install the Qt tools by entering this command in a command window::
-
- pip install pyqt5-tools
-
-1.2.3 Installation of PyQt5 and eric
-====================================
-1. Install the eric6 pre-requisites (PyQt, sip and QScintilla) by entering
- this command in a shell / command window::
-
- pip install qscintilla
-
- or ::
-
- pip3 install qscintilla
-
- This will install QScintilla and all dependencies, which are PyQt5 and sip.
-
-2. Install eric6 and configure the path to the Qt tools on the Qt page of the
- configuration dialog.
-
-3. Once the eric6 IDE is started the Qt documentation may be loaded into the
- eric web browser via the ``Settings ➡ Mange Qt Help Documents`` menu entry.
+3. Configure the path to the Qt tools on the ``Qt`` configuration page of the
+ eric6 configuration dialog.
2. Installation of translations
-------------------------------
-Translations of the eric6 IDE are available as separate downloads. There
-are two ways to install them.
+The default distribution archive of eric6 includes all supported translations
+already. If the above installation variant 1 was performed with this, you may
+skip this section.
-The first possibility is to install them together with eric6. In order
-to do that, simply extract the downloaded archives into the same place
-as the eric6 archive and follow the installation instructions above.
-
-The second possibility is to install them separately. Extract the
-downloaded archives and execute the install-i18n.py script (type
-``python install-i18n.py -h`` for some help). This way you can make the
-translations available to everybody or just to the user executing the
-installation command (if using the -p switch).
+If the ``nolang`` archive was used, translations may be added later on by
+downloading the desired language pack, extract it to a temporary directory
+and execute the install-i18n.py script (type
+``~/eric6_venv/bin/python3 install-i18n.py``).
3. Running
----------
@@ -114,10 +92,10 @@
a standalone variant simply call up eric6_unittest. This will show the same
dialog (though with a little bit less functionality) as if started from within
eric6. The web browser can be started as a standalone program by executing the
-eric6_webbrowser script.
+eric6_browser script.
Please note, the first time you start eric6 it will recognize, that it
-hasn't been configured yet and will show the configuration dialog.
+hasn't been configured yet, and will show the configuration dialog.
Please take your time and go through all the configuration items.
However, every configuration option has a meaningful default value.
@@ -134,18 +112,21 @@
in the system tray, which contains a context menu to start eric6 and all
it's utilities. Double clicking this icon starts the eric6 IDE.
-6. Autocompletion/Calltips
---------------------------
-eric6 provides an interface to the QScintilla auto-completion and calltips
+6. Completions/Calltips
+-----------------------
+eric6 provides an interface to the QScintilla completion and calltips
functionality. QScintilla2 comes with API files for Python and itself. PyQt4
-and PyQt5 contain API files as well. These are installed by default, if the
-correct installation order (see above) is followed. An API file for eric6 is
-installed in the same place.
+and PyQt5 contain API files as well. These are installed by default. An API
+file for eric6 is installed in the same place, if installation variant 1 was
+chosen.
-In order to use autocompletion and calltips in eric6 please configure these
+In order to use completions and calltips in eric6 please configure these
functions in the "Preferences Dialog" on the "Editor -> APIs",
"Editor -> Autocompletion" and "Editor -> Calltips" pages.
+Additional completions and calltip providers are available through the eric6
+plug-in system. See below for details.
+
7. Remote Debugger
------------------
In order to enable the remote debugger start eric6, open the preferences
@@ -195,25 +176,27 @@
Mercurial
This is a distributed version control system available from
- <http://www.mercurial-scm.org>. It is the one used by eric6 itself.
+ <https://www.mercurial-scm.org/>. It is the one used by eric6 itself.
+
+ Git
+ This is another (and probably more widely known) distributed version
+ control system. It is available from <https://www.git-scm.com>.
Subversion
This is a version control system available from
- <http://subversion.apache.org>. eric6 supports two different Subversion
- interfaces. One is using the svn command line tool, the other is using
- the PySvn Python interface <pysvn.tigris.org>. The selection is done
- automatically depending on the installed software. The PySvn interface
- is prefered. This automatism can be overridden an a per project basis
- using the "User Properties" dialog.
+ <https://subversion.apache.org>. eric6 supports two different
+ Subversion interfaces. One is using the svn command line tool, the
+ other is using the PySvn Python interface
+ <https://pysvn.sourceforge.io/>. The selection is done automatically
+ depending on the installed software. The PySvn interface is preferred.
+ This automatism can be overridden an a per project basis using the
+ "User Properties" dialog.
coverage.py
This is a tool to check Python code coverage. A slightly modified
version is part of the eric6 distribution. The original version is
- available from <http://www.nedbatchelder.com/code/modules/coverage.html>
-
- tabnanny
- This is a tool to check Python code for white-space related problems.
- It is part of the standard Python installation.
+ available from
+ <http://www.nedbatchelder.com/code/modules/coverage.html>
profile
This is part of the standard Python distribution and is used to profile
@@ -243,10 +226,10 @@
14. License
-----------
-eric6 (and the others) is released under the conditions of the GPL. See
-separate license file for more details. Third party software included in
-eric6 is released under their respective license and contained in the
-eric6 distribution for convenience.
+eric6 (and the others) is released under the conditions of the GPLv3. See
+separate license file ``LICENSE.GPL3`` for more details. Third party software
+included in eric6 is released under their respective license and contained in
+the eric6 distribution for convenience.
15. Bugs and other reports
--------------------------
