Reproog/novelWriter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reorganised and update install instruction in the docs

Browse Source
This commit is contained in:
Veronica K. B. Olsen
2021-02-01 17:12:59 +01:00
parent 1f2ffe7e76
commit 704103f9f1
15 changed files with 306 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/int_started.rst
+50 -195
View File
@@ -4,14 +4,22 @@
Getting Started
***************
This is a brief guide to how you can get novelWriter running on your computer. These are the
methods currently supported by the developer. Packages may also be available in other package
managers, but those are not managed by the developer. A Windows installer file is also provided on
the GitHub releases page and linked from the `main website`_.
.. _main website: https://novelwriter.io
.. _GitHub: https://github.com/vkbo/novelWriter/releases
.. _PyPi: https://pypi.org/project/novelWriter/
This section contains brief guides to how you can get novelWriter running on your computer. These
are the methods currently supported by the developer. Packages may also be available in other
package managers, but those are not managed by the developer. A Windows installer file is also
provided on the GitHub_ releases page and linked from the `main website`_.
As novelWriter matures, more options for how to install it and get it running will be added. For
non-Windows users the install process is at the present time best suited for people used to working
with the command line. But even if you're not, the install process is fairly straight forward.
with the command line. But even if you're not, the install process is fairly straightforward.
The next pages have specific install instructions for the various operating systems novelWriter can
run on. The instructions below are supplementary information, instructions for alterbative methods,
and additional build options.
.. note::
The text below assumes the command ``python`` corresponds to a Python 3 executable. For
@@ -19,13 +27,47 @@ with the command line. But even if you're not, the install process is fairly str
Linux, the scripts can also be made executable and run without the ``python`` command. Likewise,
``pip`` may need to be replaced with ``pip3``.
.. _main website: https://novelwriter.io
.. _a_started_depend:
Dependencies
============
novelWriter has been designed to rely on as few dependencies as possible. Aside from the packages
needed to communicate with the Qt GUI libraries, only one package is required for handling the XML
format of the main project file. Everything else is handled with standard Python libraries.
The following Python packages are needed to run novelWriter:
* ``pyqt5`` – needed for connecting with the Qt5 libraries.
* ``lxml`` – needed for full XML support.
* ``pyenchant`` – needed for efficient spell checking (optional).
PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work.
Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching using regular
expressions requires 5.3, and for full Unicode support, 5.13. There is no known minimum version
requirement for package ``lxml``, but the code was originally written with 4.2, which is therefore
set as the minimum. It may work on lower versions. You have to test it.
Optionally, a package can be installed to interface with the Enchant spell checking libaries, but
this isn't strictly required. If no external spell checking library is available, novelWriter falls
back to using the internal ``difflib`` of Python to check spelling. This is a much slower approach,
and it is less sophisticated than full spell checking libaries, but if you only work with small
files, the performance loss is not noticeable. The spell check library must be at least 3.0 to work
with Windows. On Linux, 2.0 also works fine.
If you install from PyPi, these dependencies should be installed automatically. If you install from
source, dependencies can still be installed from PyPi with:
.. code-block:: console
pip install -r requirements.txt
.. _a_started_install:
Installing and Running
======================
Installing via PyPi
===================
The application is written in Python 3 using Qt5 via PyQt5. It is developed on Linux, but it should
in principle work fine on other operating systems as long as dependencies are met.
@@ -58,193 +100,6 @@ When installing via pip, novelWriter can be launched from command line with:
Make sure the install location for pip is in your PATH variable. This is not always the case by
default.
.. _GitHub: https://github.com/vkbo/novelWriter/releases
.. _PyPi: https://pypi.org/project/novelWriter/
.. _a_started_depend:
Python Dependencies
-------------------
novelWriter has been designed to rely on as few dependencies as possible. Aside from the package(s)
needed to communicate with the Qt GUI libraries, only one package is required for handling the XML
format of the main project file. Everything else is handled with standard Python libraries.
The following Python packages are needed to run novelWriter:
* ``pyqt5`` – needed for connecting with the Qt5 libraries.
* ``lxml`` – needed for full XML support.
* ``pyenchant`` – needed for efficient spell checking (optional).
PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work.
Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching using regular
expressions requires 5.3, and for full Unicode support, 5.13. There is no known minimum version
requirement for package ``lxml``, but the code was originally written with 4.2, which is therefore
set as the minimum. It may work on lower versions. You have to test it.
Optionally, a package can be installed to interface with the Enchant spell checking libaries, but
this isn't strictly required. If no external spell checking library is available, novelWriter falls
back to using the internal ``difflib`` of Python to check spelling. This is a much slower approach,
and it is less sophisticated than full spell checking libaries, but if you only work with small
files, the performance loss is not noticeable. The spell check library must be at least 3.0 to work
with Windows. On Linux, 2.0 also works fine.
If you install from PyPi, these dependencies should be installed automatically. If you install from
source, dependencies can still be installed from PyPi with:
.. code-block:: console
pip install -r requirements.txt
.. _a_started_running:
Running from Source
-------------------
If all the required dependencies are met, you can run novelWriter from the command line with:
.. code-block:: console
python novelWriter.py
A few switches are supported from the command line, mostly to assist in debugging if an error is
encountered. To list all options, run:
.. code-block:: console
python novelWriter.py --help
.. _a_started_linux:
Setup on Linux
==============
The dependencies of novelWriter are generally available from Linux distro repositories. For Debian
and Ubuntu, they can be installed with:
.. code-block:: console
sudo apt install python3-pyqt5 python3-lxml python3-enchant
If you downloaded the source, you can use the provided ``setup.py`` script to install novelWriter
into the system's default Python install locations. If so, run:
.. code-block:: console
python setup.py install
To set up the novelWriter desktop launcher, the icons, and the project file association, run:
.. code-block:: console
python setup.py xdg-install
By default, these commands install novelWriter and its icons for the current user only. To install
for all users, run the script with the ``sudo`` command. Other options are also available. Run
``python setup.py help`` for a full list of install options.
This should install novelWriter to either ``~/.local/bin/novelWriter`` if installed for local user
only, or to ``/usr/local/bin/novelWriter`` if installed for all users.
.. _a_started_macos:
Setup on macOS
==============
These instructions assume you're using brew, and have Python and pip set up. If not, see the
`brew docs`_ for help. Main requirements are installed via the requirements file. You also need to
install the ``pyobjc`` package, so you must run:
.. code-block:: console
pip3 install --user -r requirements.txt
pip3 install --user pyobjc
For spell checking you may also need to install the enchant package. It comes with a lot of default
dictionaries.
.. code-block:: console
brew install enchant
With the dependencies in place, you can either launch the ``novelWriter.py`` script directly, or
run the install command:
.. code-block:: console
python setup.py install
After this, you should be able to launch novelWriter by running ``novelWriter`` in a command line
window.
Right now there isn't a better integration with macOS available. Contributions from someone more
familiar with macOS would be very much appreciated.
.. _brew docs: https://docs.brew.sh/Homebrew-and-Python
.. _a_started_windows:
Setup on Windows
================
On Windows, you have two options: You can either run from source, or install novelWriter via a
Windows installer.
.. _a_started_win_installer:
Windows Installer
-----------------
You can install novelWriter with the Windows installer for 64-bit Windows available on the
`main website`_ and GitHub_ page. This installer bundles all that is needed for novelWriter to run,
including Python and the XML and Qt libraries. When installing novelWriter this way, you don't need
to install any of the dependencies manually. The installer is made with pyinstaller and Inno Setup.
.. _a_started_win_source:
From Source
-----------
To run from source, you may first need to install Python. If you don't have it installed, you can
download it from the python.org_ website. novelWriter should work with Python 3.6 or higher, but it
is recommended that you install the latest version of Python.
Also, make sure you select the "Add Python to PATH" option during installation, otherwise the
``python`` command will not work in the command line window.
.. image:: images/python_win_install.png
:width: 600
Once Python is set up and running, you can either run novelWriter from the folder where you
extracted it, or you can build an executable and run that from a desktop icon instead.
The PyPi installer should come bundled with the Python installation, so to install dependencies,
run:
.. code-block:: console
pip install --user -r requirements.txt
.. tip::
To create a desktop shortcut to launch novelWriter, you can right click the ``novelWriter.py``
file, create a shortcut, then right click again, select "Properties" and change the target to
your python executable followed by ``novelWriter.py``. It should look something like this:
``C:\...\AppData\Local\Programs\Python\Python38\python.exe novelWriter.py``
You can also run the ``setup.py`` script to generate a single executable, or an installer.
See `Build and Install novelWriter`_ for more details or run: ``python setup.py help``.
.. _python.org: https://www.python.org/downloads/windows/
.. _Build and Install novelWriter: https://github.com/vkbo/novelWriter/blob/main/setup/README.md
.. _a_started_docs: