Skip to content

Commit c678cc5

Browse files
vkbovkbo
committed
Update install help and front page
1 parent 5e71685 commit c678cc5

File tree

15 files changed

+342
-62
lines changed

15 files changed

+342
-62
lines changed

‎requirements.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
sphinx<7.0
21
pydata-sphinx-theme>=0.15
2+
sphinx-copybutton
33
sphinx-design
44
sphinx-favicon
5+
sphinx<7.0

‎source/_templates/layout.html‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,5 @@
22
{% block extrahead %}
33
<link rel="me" href="https://fosstodon.org/@novelwriter" />
44
<link rel="me" href="https://mastodon.online/@veronica" />
5-
<link rel="me" href="https://writing.exchange/@jadzia" />
65
{{ super() }}
76
{% endblock %}

‎source/conf.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
# -- General configuration ---------------------------------------------------
2828
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
2929

30-
extensions = ["sphinx_design", "sphinx_favicon"]
30+
extensions = ["sphinx_design", "sphinx_favicon", "sphinx_copybutton"]
3131
templates_path = ["_templates"]
3232
exclude_patterns = ["generated/*.rst"]
3333
today_fmt = "%A, %-d %B %Y at %H:%M"
@@ -44,6 +44,7 @@
4444
html_static_path = ["_static"]
4545
html_extra_path = ["_extra"]
4646
html_css_files = ["custom.css"]
47+
html_show_sourcelink = False
4748
html_context = {
4849
"default_mode": "auto",
4950
"build_time": datetime.now().strftime("%Y-%m-%d %H:%M"),

‎source/download/index.rst‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,28 @@ Downloads
77
.. toctree::
88
:hidden:
99

10-
help_win
10+
self
11+
12+
.. toctree::
13+
:caption: Installation Help
14+
:hidden:
15+
16+
install_linux
17+
install_win
18+
install_mac
19+
install_pypi
20+
21+
.. toctree::
22+
:caption: Additional Info
23+
:hidden:
24+
1125
code_signing
1226

1327
This page includes all available packages for the latest release.
1428

1529
When pre-release packages for the next version of novelWriter are available, these release packages
1630
are also listed on this page. When there is no pre-release available, the section is empty.
1731

18-
You can find more information on how to set up novelWriter on the :ref:`a_started` page of the
19-
documentation.
20-
2132

2233
Latest Release
2334
==============

‎source/download/install_linux.rst‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
.. _main_install_linux:
2+
3+
*******************
4+
Installing on Linux
5+
*******************
6+
7+
.. _GitHub: https://github.com/vkbo/novelWriter
8+
.. _PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter
9+
.. _Pre-Release PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter-pre
10+
.. _Releases: https://github.com/vkbo/novelWriter/releases
11+
.. _AppImage: https://appimage.org/
12+
.. _Fedora repository: https://packages.fedoraproject.org/pkgs/novelwriter/novelwriter/
13+
14+
There are different ways to install novelWriter, depending on your Linux distro. Here is a quick overview.
15+
16+
17+
Fedora
18+
------
19+
20+
novelWriter is available in the main `Fedora repository`_ as of Fedora 41.
21+
22+
You can install it with:
23+
24+
.. code-block:: bash
25+
26+
sudo dnf install novelwriter
27+
28+
29+
Ubuntu
30+
------
31+
32+
A Personal Package Archive (PPA) is available for novelWriter on Launchpad. This is the most
33+
straightforward way to install and update novelWriter on Ubuntu. It also works for other
34+
Debian-based distros, but see the next section for more details on this.
35+
36+
The Launchpad packages `are signed by the author <https://launchpad.net/~vkbo>`__.
37+
38+
You can add the Ubuntu PPA_ and install novelWriter with the following commands.
39+
40+
.. tab-set::
41+
42+
.. tab-item:: Releases
43+
:selected:
44+
45+
.. code-block:: bash
46+
47+
sudo add-apt-repository ppa:vkbo/novelwriter
48+
sudo apt update
49+
sudo apt install novelwriter
50+
51+
.. tab-item:: Pre-Releases
52+
53+
.. code-block:: bash
54+
55+
sudo add-apt-repository ppa:vkbo/novelwriter-pre
56+
sudo apt update
57+
sudo apt install novelwriter
58+
59+
60+
Debian and Mint
61+
---------------
62+
63+
A Debian package can be downloaded from :ref:`main_download`, or from the Releases_ page on GitHub_.
64+
This package should work on both Debian, Ubuntu and Linux Mint, at least.
65+
66+
The install instructions for Ubuntu do not work on Debian and Mint as they are Ubuntu-specific.
67+
Instead, do one of the following:
68+
69+
.. tab-set::
70+
71+
.. tab-item:: Debian 13 (Trixie) and Later
72+
:selected:
73+
74+
As of Debian 13 (Trixie) and other Debian derivatives, the keyring format has changed.
75+
The following instructions use Sequoia to install the key in the correct format, and sets up
76+
the source file in the new format.
77+
78+
If you don't have Sequoia installed, first run:
79+
80+
.. code-block:: bash
81+
82+
sudo apt install sq
83+
84+
Import the keyring:
85+
86+
.. code-block:: bash
87+
88+
sudo sq network keyserver --server hkps://keyserver.ubuntu.com search "F19F1FCE50043114" \
89+
--output /usr/share/keyrings/novelwriter-ppa-keyring.gpg --overwrite
90+
91+
Add the source file:
92+
93+
.. tab-set::
94+
95+
.. tab-item:: Releases
96+
:selected:
97+
98+
.. code-block:: bash
99+
100+
sudo sh -c "cat > /etc/apt/sources.list.d/novelwriter.sources" << EOF
101+
Types: deb
102+
URIs: http://ppa.launchpad.net/vkbo/novelwriter/ubuntu/
103+
Suites: noble
104+
Components: main
105+
Signed-By: /usr/share/keyrings/novelwriter-ppa-keyring.gpg
106+
EOF
107+
108+
.. tab-item:: Pre-Releases
109+
110+
.. code-block:: bash
111+
112+
sudo sh -c "cat > /etc/apt/sources.list.d/novelwriter-pre.sources" << EOF
113+
Types: deb
114+
URIs: http://ppa.launchpad.net/vkbo/novelwriter-pre/ubuntu/
115+
Suites: noble
116+
Components: main
117+
Signed-By: /usr/share/keyrings/novelwriter-ppa-keyring.gpg
118+
EOF
119+
120+
.. tab-item:: Debian 12 (Bookworm) and Earlier
121+
122+
For Debian 12 (Bookworm) and older, and equivalent derivatives, use the old keyring format
123+
and apt sources list file format.
124+
125+
Import the keyring:
126+
127+
.. code-block:: bash
128+
129+
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/novelwriter-ppa-keyring.gpg \
130+
--keyserver hkp://keyserver.ubuntu.com:80 --recv-keys F19F1FCE50043114
131+
132+
Add the source list:
133+
134+
.. tab-set::
135+
136+
.. tab-item:: Releases
137+
:selected:
138+
139+
.. code-block:: bash
140+
141+
echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter/ubuntu noble main" | sudo tee /etc/apt/sources.list.d/novelwriter.list
142+
143+
.. tab-item:: Pre-Releases
144+
145+
.. code-block:: bash
146+
147+
echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter-pre/ubuntu noble main" | sudo tee /etc/apt/sources.list.d/novelwriter-pre.list
148+
149+
.. tip::
150+
If you get an error message like ``gpg: failed to create temporary file`` when importing the key
151+
from the Ubuntu keyserver, try creating the folder it fails on, and import the key again:
152+
153+
.. code-block:: bash
154+
155+
sudo mkdir -m 700 /root/.gnupg/
156+
157+
**Install novelWriter**
158+
159+
Then run the update and install commands as for Ubuntu:
160+
161+
.. code-block:: bash
162+
163+
sudo apt update && sudo apt install novelwriter
164+
165+
166+
AppImage Releases
167+
-----------------
168+
169+
For other Linux distros than the ones mentioned above, the primary option is AppImage_. These are
170+
completely standalone images for the app that include the necessary environment to run novelWriter.
171+
They can of course be run on any Linux distro, if you prefer this to native packages.
172+
173+
.. note::
174+
novelWriter generally doesn't support Python versions that have reached end of life. If your
175+
Linux distro still uses older Python versions and novelWriter won't run, you may want to try the
176+
AppImage instead.

‎source/download/install_mac.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. _main_install_mac:
2+
3+
*******************
4+
Installing on MacOS
5+
*******************
6+
7+
.. _GitHub: https://github.com/vkbo/novelWriter
8+
.. _Releases: https://github.com/vkbo/novelWriter/releases
9+
10+
You can install novelWriter with both its Python and library dependencies embedded using the DMG
11+
application image file from :ref:`main_download`, or from the Releases_ page on GitHub_.
12+
Installing it should be straightforward.
13+
14+
* Download the DMG file and open it. Then drag the novelWriter icon to the :guilabel:`Applications`
15+
folder on the right. This will install it into your :guilabel:`Applications`.
16+
* The first time you try to launch it, it will say that the bundle cannot be verified, simply press
17+
the :guilabel:`Open` button to add an exception.
18+
* If you are not presented with an :guilabel:`Open` button in the dialog, launch the application
19+
again by right clicking on the application in Finder and selecting :guilabel:`Open` from the
20+
context menu.
21+
22+
The context menu can also be accessed by option-clicking if you have a one button mouse. This is
23+
done by holding down the option key on your keyboard and clicking on the application in Finder.
24+
25+
.. note::
26+
The novelWriter DMG is not signed because Apple doesn't currently provide a way for non-profit
27+
open source projects to properly sign their installers. The novelWriter project doesn't have the
28+
funding to pay for a commercial software signing certificate.

‎source/download/install_pypi.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
.. _main_install_pypi:
2+
3+
********************
4+
Installing from PyPi
5+
********************
6+
7+
.. _PyPi: https://pypi.org/project/novelWriter/
8+
.. _python.org: https://www.python.org/downloads/
9+
10+
novelWriter is also available on the Python Package Index, or PyPi_. This install method works on
11+
all supported operating systems with a suitable Python environment already installed.
12+
13+
To install from PyPi you must first have the ``python`` and ``pip`` commands available on your
14+
system. You can download Python from `python.org`_. It is recommended that you install the latest
15+
version. If you are on Windows, also make sure to select the "Add Python to PATH" option during
16+
installation.
17+
18+
To install novelWriter from PyPi, use the following command:
19+
20+
.. code-block:: bash
21+
22+
pip install novelwriter
23+
24+
To upgrade an existing installation, use:
25+
26+
.. code-block:: bash
27+
28+
pip install --upgrade novelwriter
29+
30+
When installing via pip, novelWriter can be launched from command line with:
31+
32+
.. code-block:: bash
33+
34+
novelwriter
35+
36+
Make sure the install location for pip is in your PATH variable. This is not always the case by
37+
default, and then you may get a "Not Found" error when running the ``novelwriter`` command.

‎source/download/help_win.rst‎ renamed to ‎source/download/install_win.rst‎

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,11 @@ installer from either here on the novelwriter.io website, or directly from the p
3333
the :ref:`Home <main_home>` page or the :ref:`main_download` page. You can also download the
3434
``.sha256`` file on the `GitHub Releases`_ page alongside the installer.
3535

36+
.. tip::
37+
38+
If you have any issues, try uninstalling the previous version and making a fresh install. If you
39+
already had a version installed via a different method, you should uninstall that first as having
40+
multiple installations has been known to cause problems.
3641

3742
.. _main_install_win_content:
3843

@@ -46,23 +51,17 @@ The installed files for novelWriter are usually located in:
4651

4752
``C:\Program Files\novelWriter``
4853

49-
Since novelWriter is written in pure Python, there is no executable binary file (``.exe`` file).
50-
Instead, novelWriter comes with the official Python executable included. This executable is
51-
called ``python.exe``, and is signed by the "Python Software Foundation". Most of the other files
52-
in the main folder are also for Python. They are included in the installer from the
53-
`Python Website`_ when it is created.
54-
55-
The start script for novelWriter is called ``novelWriter.pyw``, and all of the code for it is in
56-
the ``novelwriter`` folder. The app code is in a number of ``.py`` files, and they are all readable
57-
in for instance Notepad. There are also a number of ``.pyc`` files, which are performance enhanced
58-
versions of the ``.py`` files, generated by Python. If you delete them, they will be created again
59-
the next time you run the app.
54+
novelWriter is written in Python, so the code is fully readable in the installation folder. As of
55+
version 2.7, a small ``novelWriter.exe`` file is used to launch the application. Also present is
56+
the official Python executable. This executable is called ``python.exe``, and is signed by the
57+
"Python Software Foundation". Most of the other files in the main folder are also for Python. They
58+
are included in the installer from the `Python Website`_ when it is created.
6059

6160
In addition to its own code, novelWriter depends on a few libraries. They are located in the
6261
``lib`` folder:
6362

64-
* ``PyQt5`` is the framework that novelWriter is built upon. It is a Python wrapper library for
65-
the `Qt Framework`_.
63+
* ``PyQt5/PyQt6`` is the framework that novelWriter is built upon. It is a Python wrapper library
64+
for the `Qt Framework`_.
6665
* ``enchant`` is a spell checker library that provides spell checking capabilities for novelWriter.
6766

6867
That's all.

‎source/generated/checksum_block.rst‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,13 @@
1-
Sha256 Checksums
2-
----------------
3-
4-
* | **Linux AppImage:** novelWriter-2.6.3.AppImage
5-
| Sha256: ``6099b28216eced371faca6d5cd52a31388964a25d0dfdde9cf62438fbbeb0887`` :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3.AppImage.sha256>`__
6-
* | **Debian Package:** novelwriter_2.6.3_all.deb
7-
| Sha256: ``490fb0cb37c9bd0d6551ffd8e09d35e9e6d313e02796b69ee68ff60708e6416c`` :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelwriter_2.6.3_all.deb.sha256>`__
8-
* | **Windows Installer:** novelwriter-2.6.3-amd64-setup.exe
9-
| Sha256: ``9c52a9cbdd35b12608319d7c3d531fc7f483ea3513dec688c1f839efd80c5460`` :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelwriter-2.6.3-amd64-setup.exe.sha256>`__
10-
* | **MacOS DMG Image (Intel):** novelWriter-2.6.3-x86_64.dmg
11-
| Sha256: ``34ba50008b0749d406c63458b68d236011c3031f92a36974be4bae233d48e261`` :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3-x86_64.dmg.sha256>`__
12-
* | **MacOS DMG Image (M1):** novelWriter-2.6.3-aarch64.dmg
13-
| Sha256: ``845bee441b92fa4018fb4dc50f3e4411a4f3174f9a30adf0f398256fd83a9487`` :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3-aarch64.dmg.sha256>`__
1+
Sha256 Checksum Files
2+
---------------------
3+
4+
Checksum files are released alongside the packages. These files can be used to verify the downloaded package.
5+
6+
* **Linux AppImage:** :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3.AppImage.sha256>`__
7+
* **Debian Package:** :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelwriter_2.6.3_all.deb.sha256>`__
8+
* **Windows Installer:** :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelwriter-2.6.3-amd64-setup.exe.sha256>`__
9+
* **MacOS DMG Image (Intel):** :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3-x86_64.dmg.sha256>`__
10+
* **MacOS DMG Image (M1):** :octicon:`download` `ShaSum File <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3-aarch64.dmg.sha256>`__
1411

1512
.. rubric:: Verify the Checksum
1613

‎source/generated/download_block.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Latest Release
2424
| **Download**
2525
| :octicon:`download` `AppImage <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3.AppImage>`__
2626
| :octicon:`download` `Debian Package <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelwriter_2.6.3_all.deb>`__
27+
| :octicon:`light-bulb` :ref:`Install Help <main_install_linux>`
2728
2829
.. grid-item::
2930
:columns: 5
@@ -72,7 +73,7 @@ Latest Release
7273
| **Download**
7374
| :octicon:`download` `DMG Image (Intel) <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3-x86_64.dmg>`__
7475
| :octicon:`download` `DMG Image (M1) <https://github.com/vkbo/novelWriter/releases/download/v2.6.3/novelWriter-2.6.3-aarch64.dmg>`__
75-
| :octicon:`light-bulb` :ref:`Install Help <a_started_macos>`
76+
| :octicon:`light-bulb` :ref:`Install Help <main_install_mac>`
7677
7778
.. grid-item::
7879
:columns: 5

0 commit comments

Comments
 (0)