Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Issue #570: Clarify install instructions #576

Merged
merged 3 commits into from
Jan 19, 2021
Merged

Issue #570: Clarify install instructions #576

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ed93137
Clarify install instructions on dependency install
vkbo Jan 19, 2021
2c191a9
Minor modification to the macOS workflow
vkbo Jan 19, 2021
5c4e230
No need to duplicate instructions, but added a TLDR section
vkbo Jan 19, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/test_mac.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ jobs:
run: |
pip install --upgrade pip
pip install -r requirements.txt
pip install pyobjc
pip install pytest-timeout
pip install pytest-cov
pip install pytest-qt
Expand Down
123 changes: 28 additions & 95 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ is primarily saved in JSON files.
The full documentation is available at
[novelwriter.readthedocs.io](https://novelwriter.readthedocs.io/).

The contributing guide is available in [CONTRIBUTING](CONTRIBUTING.md).
The contributing guide is available at
[CONTRIBUTING](https://github.com/vkbo/novelWriter/blob/main/CONTRIBUTING.md).


## Implementation
Expand All @@ -40,118 +41,50 @@ tests are run on the latest versions of Ubuntu Linux, Windows Server and macOS.

# Installing and Running

novelWriter is available on [pypi.org](https://pypi.org/project/novelWriter/), and can be installed
with:
```bash
pip install novelwriter
```

To upgrade an existing installation, use:
```bash
pip install --upgrade novelwriter
```

Dependencies are installed automatically, but can generally be installed with:
```bash
pip install -r requirements.txt
```
For install instructions, please check the [documentation](https://novelwriter.readthedocs.io/) in
the [Getting Started](https://novelwriter.readthedocs.io/en/latest/int_started.html) section.

Below are some brief instructions on how to get started on different operating systems.
## TLDR Instructions

**Note:** You may need to replace `python` with `python3` and `pip` with `pip3` in the instructions
below on some systems. You may also want to add the `--user` flag for `pip` to install in your user
space only.

## Linux
### Install from PyPi

Either download the source, or install with pip.

If you run from source, install the dependencies via pip, or directly from the OS repo. There are
very few dependencies, and they should be available in the standard repo. The Python packages
needed are `pyqt5`, `lxml` and `pyenchant`.

### Installing from Source

You can also install novelWriter from source with:
novelWriter is available on [pypi.org](https://pypi.org/project/novelWriter/), and can be installed
with:
```bash
python setup.py sample
sudo python setup.py install
sudo python setup.py xdg-install
pip install novelwriter
```

The last line will install the application icons and set up a launcher for novelWriter. The script
may prompt you to choose which executable to configure if it finds more than one.

**Note:** If your distro has multiple versions of Python installed, you may need to use the
`python3` command instead of `python`.

### Running from Source

If you want to run directly from the source, the application can be started with:
Dependencies should be installed automatically, but can also be installed directly with:
with:
```bash
./novelWriter.py
pip install pyqt5 lxml pyenchant
```

You can also create a launcher for running directly from source with:
### Setup on Linux

If you're running from source, the following commands will set up novelWriter on Linux:
```bash
python3 setup.py xdg-install
pip install -r requirements.txt
python setup.py install
python setup.py xdg-install
```
This will install the launcher and icons for the current user. To install them system-wide, run the
above command with `sudo` or as root.

For more install options, see [Build and Install novelWriter](setup/README.md).

### Setup on macOS

## macOS

These instructions assume you're using brew, and have Python and pip set up. If not, see the
[brew docs](https://docs.brew.sh/Homebrew-and-Python) for help.

Main requirements are installed via the requirements file. You also need to install the `pyobjc`
package on macOS, so you must run:
If you're running from source, the following commands will set up novelWriter on macOS:
```bash
brew install enchant
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.
```bash
brew install enchant
```

## Windows

On Windows, you may first need to install Python. See the [python.org](https://www.python.org/)
website for download packages. It is recommended that you install the latest version of Python 3.8.

To install dependencies, run:
```bash
pip install --user -r requirements.txt
```

**Note:** On Windows, make sure Python3 is in your PATH if you want to launch novelWriter from
command line. You can also right click the `novelWriter.py` file, create a shortcut, then right
click again, select "Properties" and change the target to your python executable and
`novelWriter.py`.

It should look something like this:
```
C:\...\AppData\Local\Programs\Python\Python38\python.exe novelWriter.py
```

You can also run the `make.py` script to generate a single executable, or an installer.
See [Build and Install novelWriter](setup/README.md) for more details.


## Package Versions

Exporting to Markdown requires PyQt/Qt 5.14. There are no known minimum for `lxml`, but the code
was originally written with 4.2. The optional spell check library must be at least 3.0.0 to work
with Windows 64 bit systems. On Linux, 2.0.0 also works fine.
### Setup on Windows

If no external spell checking tool is installed, novelWriter will use a basic spell checker based
on standard Python package `difflib`. Currently, only English dictionaries are available for this
spell checker, but more can be added to the `nw/assets/dict` folder. See the
[README](nw/assets/dict/README.md) file in that folder for how to generate more dictionaries. Note
that the difflib-based option is both slow and limited.
For Windows, you can either install via PyPi, or use the Windows installer available from the
[releases](https://github.com/vkbo/novelWriter/releases) page.

## Debugging

Expand Down Expand Up @@ -249,7 +182,7 @@ to quickly navigate between the documents while editing.

This is Open Source software, and novelWriter is licensed under GPLv3. See the
[GNU General Public License website](https://www.gnu.org/licenses/gpl-3.0.en.html) for more
details, or consult the [LICENSE](LICENSE.md) file.
details, or consult the [LICENSE](https://github.com/vkbo/novelWriter/blob/main/LICENSE.md) file.

Bundled assets have the following licenses:

Expand Down
4 changes: 2 additions & 2 deletions docs/source/int_started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,8 +82,8 @@ and it is less sophisticated than full spell checking libaries, but if you only
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. They can be
manually installed with:
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

Expand Down