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

Update "Getting Started" in docs (#1366)

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2023-02-13 19:24:35 +01:00
committed by GitHub
parent c6da74b21c d78f13839e
commit c8182c0293
1 changed files with 65 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/int_started.rst
+65 -147
View File
@@ -4,43 +4,35 @@
Getting Started
***************
.. _brew docs: https://docs.brew.sh/Homebrew-and-Python
.. _Enchant: https://abiword.github.io/enchant/
.. _GitHub: https://github.com/vkbo/novelWriter
.. _macOS: https://github.com/vkbo/novelWriter/issues/867
.. _main website: https://novelwriter.io
.. _PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter
.. _Pre-Release PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter-pre
.. _PyPi: https://pypi.org/project/novelWriter/
.. _python.org: https://www.python.org/downloads/windows
.. _Releases: https://github.com/vkbo/novelWriter/releases
.. _RPM: https://github.com/vkbo/novelWriter/issues/907
.. _AppImage: https://appimage.org/
If you are using Windows or a Debian-based Linux distribtuion, you can install novelWriter from
package installers. If you are on macOS, you have the option to run novelWriter from a standalone
folder. See :ref:`a_started_minimal`. This option is also available for Windows and Linux. The
third option is to install novelWriter from the Python Package Index. See :ref:`a_started_pip`.
Package installers are available for all major platforms, including Linux, Windows and MacOS. See
below for install instructions for each platform.
You can also install novelWriter from the Python Package Index (PyPi). See :ref:`a_started_pip`.
Installing from PyPi does not set up icon launchers, so you will either have to do this yourself,
or start novelWriter from command line.
Spell checking in novelWriter is provided by a third party library called Enchant_. Generally, it
should pull dictionaries from your operating system automatically. However, on Windows they must be
installed manually. See :ref:`a_custom_dict` for more details.
.. admonition:: Help Wanted
:class: seealso
If you would like to help making more installers, the project is currently looking for people
who can help make releases for Red Hat-based Linux distros (RPM) and for macOS. See the issues
posted for RPM_ and macOS_ on GitHub_.
.. _a_started_windows:
Install on Windows
==================
Installing on Windows
=====================
You can install novelWriter with both Python and library dependencies embedded using the Windows
Installer (setup.exe) file from the `main website`_, or from the Releases_ page on GitHub.
Installer (setup.exe) file from the `main website`_, or from the Releases_ page on GitHub_.
Installing it should be straightforward.
If you have any issues, try uninstalling the previous version and making a fresh install. If you
@@ -49,10 +41,10 @@ already had a version installed via a different method, you should uninstall tha
.. _a_started_linux:
Install on Linux
================
Installing on Linux
===================
A Debian package can be downloaded from the `main website`_, or from the Releases_ page on GitHub.
A Debian package can be downloaded from the `main website`_, or from the Releases_ page on GitHub_.
This package should work on both Debian, Ubuntu and Linux Mint, at least.
If you prefer, you can also add the novelWriter repository on Launchpad to your package manager.
@@ -69,7 +61,7 @@ You can add the Ubuntu PPA_ and install novelWriter with the following commands.
sudo apt update
sudo apt install novelwriter
If you want pre-releases, add the ``ppa:vkbo/novelwriter-pre`` repository instead.
If you want the `Pre-Release PPA`_ instead, add the ``ppa:vkbo/novelwriter-pre`` repository.
Debian and Mint
@@ -83,7 +75,7 @@ Instead, run the following commands to add the repository and key:
.. code-block:: bash
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/novelwriter-ppa-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys F19F1FCE50043114
echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/novelwriter.list
echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter/ubuntu jammy main" | sudo tee /etc/apt/sources.list.d/novelwriter.list
Then run the update and install commands as for Ubuntu:
@@ -94,8 +86,8 @@ Then run the update and install commands as for Ubuntu:
.. note::
Please use the Ubuntu 20.04 (focal) packages for Debian. The newer Ubuntu packages use a
different compression algorithm that Debian doesn't currently support.
You may need to use the Ubuntu 20.04 (focal) packages for Debian 11 or earlier. The newer Ubuntu
packages use a different compression algorithm that may not be supported.
AppImage Releases
@@ -108,141 +100,36 @@ They can of course be run on any Linux distro, if you prefer this to native pack
.. _a_started_macos:
Install on MacOS
================
Installing on MacOS
===================
You can install novelWriter with both its Python and library dependencies embedded using the
DMG application image file from the `main website`_, or from the Releases_ page on GitHub.
Installing it should be straightforward.
You can install novelWriter with both its Python and library dependencies embedded using the DMG
application image file from the `main website`_, or from the Releases_ page on GitHub_. Installing
it should be straightforward.
Download the DMG file and open it. Then drag the novelWriter icon to the Applications folder on
the right. This will install it into your Applications. The first time you try to launch it, it will
say that the bundle cannot be verified, simply press the “open” button to add an exception.
If you are not presented with an "open" button in the dialog launch the application again by
right clicking on the application in Finder and selecting "Open" from the context menu.
* Download the DMG file and open it. Then drag the novelWriter icon to the :guilabel:`Applications`
folder on the right. This will install it into your :guilabel:`Applications`.
* The first time you try to launch it, it will say that the bundle cannot be verified, simply press
the :guilabel:`Open` button to add an exception.
* If you are not presented with an :guilabel:`Open` button in the dialog launch the application
again by right clicking on the application in Finder and selecting :guilabel:`Open` from the
context menu.
The context menu can also be accessed by option clicking if you have a one button mouse.
This is done by holding down the option key on your keyboard and clicking on the application in Finder.
.. _a_started_minimal:
Minimal Package Install
=======================
On the `main website`_ and on the Releases_ page on GitHub you will also find "Minimal Package"
install files for Windows, Linux and macOS. These are zip files of just the files you need to run
novelWriter on that specific platform.
These zip files don't include any dependencies, so you must install them separately.
.. _a_started_minimal_windows:
Minimal Package on Windows
--------------------------
First, make sure you have Python installed on your system. If you don't, you can download it from
`python.org`_. Python 3.7 or higher is required, but it is recommended that you install the latest
version.
Make sure you select the "Add Python to PATH" option during installation, otherwise the ``python``
command will not work in the command line window.
.. figure:: images/python_win_install.png
:align: center
:width: 500
When Python is installed, extract the novelWriter zip file and move the extracted folder to a
suitable location. You should probably not keep it on your desktop or in your downloads folder
where it may be accidentally deleted. Instead, move and rename it to for instance
``C:\novelWriter``.
After you've got the folder where you want it, open it and double-click the file named
``windows_install.bat``. This will open a command line window and run the setup script to install
dependencies, and add desktop and start menu icons.
Running ``windows_uninstall.bat`` will reverse the process if you wish to uninstall. After that,
you can just delete the novelWriter folder.
.. _a_started_minimal_linux:
Minimal Package on Linux
------------------------
On Linux you need to install the following packages on Debian-based distros, including Ubuntu and
Linux Mint:
.. code-block:: bash
sudo apt install python3-pyqt5 python3-lxml python3-enchant
On Fedora, you need the following packages:
.. code-block:: bash
sudo dnf install python3-qt5 python3-lxml python3-enchant
A standard desktop launcher can be installed via the main setup script. It will create the needed
desktop file and add it to the Applications menu. The necessary icons will also be installed, and a
file association with ``.nwx`` project files added.
To set this up, run the following from inside the extracted novelWriter folder:
.. code-block:: bash
python3 setup.py xdg-install
This installs icons for the current user. Run with ``sudo`` to install system-wide.
To uninstall the icons, run:
.. code-block:: bash
python3 setup.py xdg-uninstall
.. _a_started_minimal_mac:
Minimal Package on macOS
------------------------
These instructions assume you're using brew, and have Python and pip set up. If not, see the
`brew docs`_ for help. The main requirements for novelWriter are installed via the requirements
file. You also need to install the ``pyobjc`` package, so you should run:
.. code-block:: bash
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:: bash
brew install enchant
With the dependencies in place, you can launch the ``novelWriter.py`` script directly to run
novelWriter.
.. note::
Right now there isn't a better integration with macOS available. Contributions from someone more
familiar with macOS would be very much appreciated. See the macOS_ issue on GitHub.
The context menu can also be accessed by option-clicking if you have a one button mouse. This is
done by holding down the option key on your keyboard and clicking on the application in Finder.
.. _a_started_pip:
Install from PyPi
=================
Installing from PyPi
====================
novelWriter is also available on the Python Package Index, or PyPi_. This install method works on
all supported operating systems.
To install from PyPi you must first have the ``python`` and ``pip`` commands available on your
system. If you don't, see specific instructions for your operating system in this documentation on
how to get the Python environment set up.
system. If you are on Windows, and don't have Python installed, see :ref:`a_started_win_py` for
help.
To install novelWriter from PyPi, use the following command:
@@ -266,4 +153,35 @@ Make sure the install location for pip is in your PATH variable. This is not alw
default.
.. note::
On systems with both Python 2 and 3, you may have to replace the ``pip`` command with ``pip3``.
.. _a_started_win_py:
Installing Python on Windows
----------------------------
In order to run novelWriter from source, or install from PyPi, you need to have Python set up on
your system. Unlike Linux and MacOS, Windows does not come with Python pre-installed.
You can download Python from `python.org`_. Python 3.7 or higher is required for running
novelWriter, but it is recommended that you install the latest version.
Make sure you select the "Add Python to PATH" option during installation, otherwise the ``python``
command will not work in the command line window.
.. figure:: images/python_win_install.png
:align: center
:width: 500
Screenshot of the Python installer on Windows.
When Python is installed, you should be able to run Python commands from the COmmand Prompt or
from PowerShell. You can verify this by running:
.. code-block:: bash
python --version
This should print out the version number of the Python installation.