Merge pull request #2533 from Exirel/docs-install

docs: install and running instance documentation

contrib/README.md

@@ -1,28 +1,5 @@
 This folder contains contributed files for use with Sopel.
 
-## Service configuration
-
-`sopel.service` and `sopel.cfg` are designed to be distributed by third parties
-such as Fedora Project or Arch Linux.
-
-`sopel.cfg` is a default configuration file for Sopel, that assumes the OS is
-new enough to have `/run` and `/usr/lib/tmpfiles.d`
-
-`sopel.service` is a systemd service file, and `[email protected]` is a
-multi-instance template. Both assume you are using a rather recent Sopel; that
-the system has a special user named `sopel` designated for running the bot; and
-that this user has access to `/run/sopel` (should be setup by `sopel.conf` in
-`/usr/lib/tmpfiles.d`), `/var/log/sopel` and `/var/lib/sopel`
-
-Default installation paths:
-
-```
-sopel.cfg	/etc
-sopel.conf	/usr/lib/tmpfiles.d
-sopel.service	/usr/lib/systemd/system
-[email protected]	/usr/lib/systemd/system
-```
-
 ## tox
 
 `tox.ini` and `toxfile.py` provide support for running Sopel's QA automation

docs/source/faq.rst

@@ -0,0 +1,40 @@
+==========================
+Frequently Asked Questions
+==========================
+
+.. _faq-contact-us:
+
+How to contact us?
+==================
+
+You can contact us by joining the development and community channel on IRC:
+
+* connect to the `libera.chat`__ network
+* and join the ``#sopel`` channel
+
+We talk about the bot's development, and we answer questions from bot owners &
+plugin authors as much as we can. We try to keep it as friendly as possible;
+sometimes we also just chat about about non-development topics.
+
+All conversations are in English (except when someone swears in French).
+
+.. __: https://libera.chat/guides/connect
+
+
+.. _faq-bug-report:
+
+How to report a bug?
+====================
+
+The best place to report a bug is to `open an issue on GitHub`__. We have
+configured some templates to help and guide you through the process and
+hopefully to make it easier for you.
+
+Before submitting your bug, you can `search existing issues`__ to see if there
+is one open already.
+
+Do not hesitate to :ref:`contact us<faq-contact-us>` if you are unsure about
+your bug report.
+
+.. __: https://github.com/sopel-irc/sopel/issues/new/choose
+.. __: https://github.com/sopel-irc/sopel/issues

docs/source/index.rst

@@ -1,28 +1,30 @@
 .. title:: Sopel IRC Bot
 
+=============
 Sopel IRC Bot
 =============
 
 `Sopel <https://sopel.chat>`_ is a Python IRC bot framework. It is designed to
 enable easily writing new utilities and features for your IRC channels. 
 
+
 Quick links
------------
+===========
 
 * `Latest releases <https://github.com/sopel-irc/sopel/releases>`_
 * `Source code <https://github.com/sopel-irc/sopel>`_
+* :doc:`faq`
 
-..
-    Eventually, add installation instructions to Sphinx docs?
 
 Documentation
--------------
+=============
 
 .. toctree::
     :maxdepth: 2
     :titlesonly:
 
     run
+    faq
     plugin
     package
     tests

docs/source/plugin/tutorials/configuration-and-setup.rst

@@ -5,7 +5,7 @@ Configuration and plugin setup
 Maybe you :doc:`played with commands <playing-with-commands>` for your
 plugin and now you want to make your plugin configurable. If you run an
 instance of Sopel yourself, you probably had to open and edit its
-:doc:`configuration</configuration>` file.
+:doc:`configuration</run/configuration>` file.
 
 Usually located in the ``.sopel/`` folder under your home directory, the
 configuration file is an INI file with sections defined by Sopel's core and by
@@ -107,7 +107,7 @@ declare and to setup your plugin configuration, and you can read more about
 :ref:`plugin configuration <plugin-anatomy-config>`,
 which includes a section about the configuration wizard as well. You can also
 see Sopel's own configuration in
-:doc:`the configuration chapter </configuration>`.
+:doc:`the configuration chapter </run/configuration>`.
 
 Once you are familiar with the concept, you can also read deeper into the
 reference documentation for the :mod:`sopel.config` module.

docs/source/run.rst

@@ -1,7 +1,26 @@
+===============
 Running the bot
 ===============
 
+Welcome to this part of the documentation, dedicated to all who do or want to
+run a Sopel instance. This guide will help you set up your instance and manage
+your plugins and your configuration.
+
+.. note::
+
+    Sopel tries to be as simple as possible, however "simple" can be very
+    subjective, so do not hesitate to ask questions to the maintainers on IRC
+    (on the :ref:`#sopel channel<faq-contact-us>` on libera.chat) or through
+    Sopel's `GitHub repository`__. This guide is far from perfect, and we
+    appreciate feedback to make it better for everyone.
+
 .. toctree::
+    :titlesonly:
+
+    run/install
+    run/plugin
+    run/service
+    run/cli
+    run/configuration
 
-    cli
-    configuration
+.. __: https://github.com/sopel-irc/sopel

docs/source/run/install.rst

@@ -0,0 +1,139 @@
+=============
+Install Guide
+=============
+
+.. highlight:: shell
+
+Installation Requirements
+=========================
+
+To install Sopel, you will need:
+
+* Python 3.8 or above
+* Pip, the official Python package installer
+
+.. important::
+
+    Before installing Sopel, you should know which version of Python, and which
+    Python interpreter you are using for that. For instance, it can be named
+    ``python3`` or just ``python`` depending on your system and setup. In this
+    guide we will refer to the Python interpreter you want to use as
+    ``python3``.
+
+Official Release
+================
+
+The official release of Sopel is `available at PyPI`__. The
+recommended way to install Sopel from pypi.org is to perform the following
+command::
+
+    python3 -m pip install sopel
+
+This will ensure that Sopel is installed for the Python interpreter you want to
+use. You do not need to have root access to install Sopel. To check that Sopel
+is indeed installed, you can run the following line::
+
+    python3 -c "import sopel; print(sopel.__version__)"
+
+This will show the installed version of Sopel for this interpreter.
+
+When a new version of Sopel is released, you can update your install by reusing
+the same command with the ``-U`` option (short for ``--upgrade``)::
+
+    python3 -m pip install -U sopel
+
+You must restart Sopel for the update to take effect.
+
+.. __: https://pypi.org/project/sopel/
+
+Installing from Source
+======================
+
+For development purposes or to test a future release, you may want to install
+Sopel directly from its `source repository`__ on GitHub. To install from
+source, first select the version you want to install, and refer to the
+``README.rst`` file for instructions.
+
+We strongly recommend to use a virtualenv or other isolation mechanism so as to
+prevent any conflicts with your system's Python interpreter and libraries.
+
+.. warning::
+
+    Although possible, source installations are not supported. If you install
+    from sources, you may encounter unexpected bugs and unstable behaviors, and
+    we fully expect you to either find a solution by yourself, revert to a
+    previous version, or wait for a fix without an ETA.
+
+    However, we do appreciate :ref:`bug reports<faq-bug-report>` (with logs and
+    configuration details) and feedback. In that case,
+    :ref:`reaching out to us on IRC<faq-contact-us>` is the best approach.
+
+.. __: https://github.com/sopel-irc/sopel
+
+
+First run
+=========
+
+Once Sopel is installed, you should have access to a ``sopel`` command, as well
+as :doc:`other commands <cli>`.
+
+.. note::
+
+    By default, ``pip`` will install the command in ``~/.local/bin/``, which
+    might not be on your ``PATH``. You will need to add this folder to your
+    ``PATH`` for your shell to see the command.
+
+    For example, you could add this to your ``~/.profile`` file (works on
+    Ubuntu 22.04)::
+
+        # set PATH so it includes user's private bin if it exists
+        if [ -d "$HOME/.local/bin" ] ; then
+            PATH="$HOME/.local/bin:$PATH"
+        fi
+
+    Refer to your operating system's documentation for more information on how
+    to configure your ``PATH``.
+
+Initial Configuration
+---------------------
+
+To run the bot, you need a :doc:`configuration file <configuration>`, which you
+can create with the following command::
+
+    sopel configure
+
+This will run a wizard that helps you create a configuration file. It will
+ask you questions to fill in the details. When you see something in ``[square
+brackets]``, that's the default setting, and you can just hit :kbd:`Enter` to keep
+it. We recommend selecting a custom nick for your bot during configuration.
+
+This wizard doesn't cover every option, only the ones which are needed to get
+the bot running. The :doc:`core config settings <configuration>` are all
+documented if you want to make other tweaks.
+
+Finally, the wizard will ask you about configuration settings for plugins. This
+will automatically detect what plugins you have available, and run their
+configuration utility if they have one.
+
+Once you are done, you can always re-run the same command and accept the values
+you already set and change only what you need.
+
+Start the Bot
+-------------
+
+Once you have properly configured your bot, you are now ready to start it for
+the first time. The command to do so is the following::
+
+    sopel start
+
+.. note::
+
+    Some IRC networks require nick registration or special configuration
+    for connecting. Refer to your IRC network for more information about
+    what steps may be necessary to run your bot there.
+
+Sopel will output log information informing you of its startup progress, such
+as loading plugins, connecting to the network, and joining channels.
+
+To stop the bot, simply exit the process (e.g. with :kbd:`Control+c`) and
+Sopel will ``QUIT`` IRC, perform its shutdown tasks, and gracefully exit.