start writing docs properly, not in the README

10 files changed, 468 insertions, 47 deletions

diff --git a/.gitignore b/.gitignore
index fd9f6ed..3afaa13 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
 .coverage
 coverage.xml
 build/
+_build/
 dist/
 .tox/
 nosetests.xml
diff --git a/README.md b/README.md
index 5881f94..d6a1ba9 100644
--- a/README.md
+++ b/README.md
@@ -13,53 +13,9 @@ features are still lacking.
 Installation
 ------------
 
-- Generate a fresh virtual environment (recommended):
-
-      virtualenv .venv
-
-- Install `fietsboek`:
-
-      .venv/bin/pip install .
-
-- (Optionally: Install `lxml` to speed up GPX parsing)
-
-      .venv/bin/pip install lxml
-
-- Adjust `production.ini` to your needs, mainly check the following settings:
-
-      sqlalchemy.url - see https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls
-      session_key - set this to a random secret which is used to sign session keys
-      available_locales - set this to the list of locales you want to support
-                          (by default, English and German translations are shipped)
-      enable_account_registration - whether users should be able to create new accounts
-                                    (set this to false for a private instance)
-      pyramid.default_locale_name - set the default language
-      email.from - the address that Fietsboek email's will be sent from
-      email.smtp_url - the URL of the SMTP server to send emails
-                       (smtp://host:port, smtp+ssl://host:port, smtp+starttls://host:port)
-      email.smtp_user, email.smtp_password - SMTP login information
-
-- Create the database tables:
-
-      .venv/bin/alembic -c production.ini upgrade head
-
-- Create the admin user
-
-      .venv/bin/fietsctl -c production.ini useradd --admin
-
-- Start Fietsboek:
-
-      .venv/bin/pserve production.ini
-
-This runs Fietsboek using Pyramid's [Waitress](https://docs.pylonsproject.org/projects/waitress/en/stable/index.html)
-server. If you need a better performance, read [the corresponding
-section](https://docs.pylonsproject.org/projects/waitress/en/stable/index.html)
-in the Pyramid documentation and set up Fietsboek using an alternative server,
-such as `gunicorn` or `mod_wsgi`.
-
-Note that it is advised to use a reverse proxy in front of Fietsboek to handle
-SSL. **Not setting up a SSL capable reverse proxy puts the security of your
-users at risk!**
+Setup instructions are in the documentation. You can either build it locally
+using [Sphinx](https://www.sphinx-doc.org/), or view the generated version
+online: https://kingdread.de/fietsboek/
 
 Development
 -----------
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..d4bb2cb
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/administration/backup.rst b/doc/administration/backup.rst
new file mode 100644
index 0000000..9566e38
--- /dev/null
+++ b/doc/administration/backup.rst
@@ -0,0 +1,61 @@
+Backup & Restore
+================
+
+A well-maintained Fietsboek instance should have regular backups configured in
+case data is lost due unforseen reasons.
+
+.. note::
+
+    As a rule of thumb: A backup that you haven't restored is not a backup!
+
+    Part of the backup process is to ensure that the backups actually contain
+    the necessary data and that the restoration process works. Make sure to
+    test your backups on a separate installation of Fietsboek.
+
+Backup
+------
+
+All of the Fietsboek data is contained in the database. You should refer to the
+manual of your DBMS to see what the procedure for a backup is. Using the
+preferred way for your DBMS ensures that your backup represents a consistent
+state of the database.
+
+In addition to the actual data, you should also note down the Fietsboek version
+and the database schema version, as backups can only be restored to the same
+version!
+
+To view the fietsboek version in case you are using ``git``, you can use the
+following command:
+
+.. code:: bash
+
+    git rev-parse HEAD
+
+To view the database schema version, use ``alembic``:
+
+.. code:: bash
+
+    .venv/bin/alembic -c development.ini current
+
+Note those value in addition to your backup.
+
+Restore
+-------
+
+The restoration process works in three steps:
+
+First, we ensure that we are on the correct Fietsboek version. If you are using
+``git``, this can be done with ``git checkout``:
+
+.. code:: bash
+
+    git checkout NOTED_GIT_VERSION_HERE
+
+Then, we get the database schema to the right version:
+
+.. code:: bash
+
+    .venv/bin/alembic -c production.ini upgrade NOTED_ALEMBIC_VERSION_HERE
+
+Finally, we can restore the data. This step is dependent on the DBMS that you,
+therefore you should consult its documentation.
diff --git a/doc/administration/configuration.rst b/doc/administration/configuration.rst
new file mode 100644
index 0000000..48afde1
--- /dev/null
+++ b/doc/administration/configuration.rst
@@ -0,0 +1,66 @@
+Configuration
+=============
+
+The main configuration of Fietsboek is done via ``.ini``-files. By default,
+three such files exist:
+
+* ``production.ini`` contains the configuration for the production environment.
+  It turns off debugging features (as they are a security risk!) and should
+  contain the URL of the production database. This is the main file you want to
+  use if you just want to deploy Fietsboek.
+* ``development.ini`` contains the configuration for local development on
+  Fietsboek. **This should not be used for production purposes, as it provides
+  debugging information that poses a security risk!**
+* ``testing.ini`` contains the configuration that the automated tests will use.
+
+Most of the configuration is in the ``[app:main]`` category and looks like this:
+
+.. code:: ini
+
+    [app:main]
+    use = egg:fietsboek
+
+    pyramid.reload_templates = false
+    pyramid.debug_authorization = false
+    pyramid.debug_notfound = false
+    pyramid.debug_routematch = false
+    pyramid.default_locale_name = en
+
+    email.from = fietsboek@kingdread.de
+    email.smtp_url = debug://localhost:1025
+
+    available_locales = en de
+    enable_account_registration = true
+
+    session_key = <EDIT THIS>
+
+    sqlalchemy.url = sqlite:///%(here)s/fietsboek.sqlite
+
+    retry.attempts = 3
+
+* You should leave the ``use``, ``pyramid.reload_templates`` and
+  ``pyramid.debug_*`` settings as they are.
+* ``pyramid.default_locale_name`` can be used to set the default language of
+  the installation. Note that Fietsboek will try to detect the user's language,
+  so the ``default_locale_name`` is used as a fallback.
+* ``available_locales`` sets the list of available languages. Currently,
+  Fietsboek ships with English ("en") and German ("de"). Removing a language
+  from this list will make it unavailable. If you create a custom language
+  locally, make sure to add it to this list here!
+* ``enable_account_registration`` can be used to enable and disable the
+  creation of new accounts via the web interface, for example if you want to
+  have a private instance. New accounts can always be created using the CLI
+  management tool.
+* ``email.from`` sets the sender of emails, for example for account verifications.
+* ``email.smtp_url`` sets the URL of the SMTP server. The following formats are accepted:
+
+  * ``debug://`` a debug implementation that simply prints emails to the
+    standard output. Should not be used in production, as no emails would ever
+    arrive.
+  * ``smtp://host:port`` use the given SMTP server (without transport encryption!)
+  * ``smtp+ssl://host:port`` use the given SMTP server over a SSL connection
+  * ``smtp+starttls://host:port`` use the given SMTP server and the STARTTLS
+    command to start an encrypted channel.
+
+* ``email.username`` and ``email.password`` can be used to set the login
+  information for the SMTP server.
diff --git a/doc/administration/installation.rst b/doc/administration/installation.rst
new file mode 100644
index 0000000..b8ede06
--- /dev/null
+++ b/doc/administration/installation.rst
@@ -0,0 +1,109 @@
+Installation
+============
+
+This document will outline the installation process of Fietsboek, step-by-step.
+
+Creating an Environment
+-----------------------
+
+It is advised that you keep your Fietsboek installation in a separate `virtual
+environment <https://virtualenv.pypa.io/en/latest/>`__. This makes sure that
+the dependencies that Fietsboek pulls in do not interfere with your system's
+libraries, and it makes sure that you can upgrade those components easily
+without affecting other installed programs.
+
+We will assume that you create your environment in the ``.venv`` folder. Any
+path can be choosen, you just need to remember it for later
+
+.. code:: bash
+
+    # If Python 3 is the default on your system:
+    virtualenv .venv
+    # Otherwise:
+    virtualenv -p python3 .venv
+
+Installing the Python Modules
+-----------------------------
+
+The Python package manager takes care of installing all dependencies, all you
+need to do is tell it to install Fietsboek:
+
+.. code:: bash
+
+    # Assuming that we are in the Fietsboek folder
+    .venv/bin/pip install .
+    # Alternatively
+    .venv/bin/pip path/to/fietsboek/repository
+
+Optionally, you can install ``lxml``, which provides a faster XML parser to
+process the GPX files:
+
+.. code:: bash
+
+    .venv/bin/pip install lxml
+
+Configuring Fietsboek
+---------------------
+
+Before you can run Fietsboek, you need to adjust your configuration. See
+:doc:`configuration` for that.
+
+Setting up the Database
+-----------------------
+
+Fietsboek uses `alembic <https://alembic.sqlalchemy.org/en/latest/>`__ to
+manage the database scheme. To set up the initial database, run
+
+.. code:: bash
+
+    .venv/bin/alembic -c production.ini upgrade head
+
+Adding an Administrator User
+----------------------------
+
+You can use the ``fietsctl`` command line program to add administrator users:
+
+.. code:: bash
+
+    .venv/bin/fietsctl -c production.ini useradd --admin
+
+Running Fietsboek
+-----------------
+
+To run Fietsboek, simply run
+
+.. code:: bash
+
+    .venv/bin/pserve production.ini
+
+.. warning::
+
+    It is strongly advised that you use a httpd configured with SSL as a
+    reverse proxy (such as `Apache2
+    <https://httpd.apache.org/docs/current/howto/reverse_proxy.html>`__ or
+    `nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`__) to
+    handle external traffic to Fietsboek!
+
+    Fietsboek itself does not use SSL encryption for its traffic, and not
+    setting up a proper reverse proxy will put your user's data at risk!
+
+The default server uses `waitress
+<https://docs.pylonsproject.org/projects/waitress/en/stable/index.html>`__ and
+should be enough for small to medium traffic. It is implemented purely in
+Python and should run on most systems.
+
+Alternatively, you can switch to `gunicorn <https://gunicorn.org/>`__ or
+`mod_wsgi <https://modwsgi.readthedocs.io/en/master/>`__ for better
+performance. For those, refer to the Pyramid documentation for more information:
+
+* `gunicorn
+  <https://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/deployment/gunicorn.html>`__
+* `mod_wsgi
+  <https://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/modwsgi/index.html>`__
+
+Maintaining Fietsboek
+---------------------
+
+A good installation should be well-oiled, which means it should be
+:doc:`updated <upgrading>` to new versions and :doc:`backups <backup>` should
+be done frequently.
diff --git a/doc/administration/upgrading.rst b/doc/administration/upgrading.rst
new file mode 100644
index 0000000..4bdc656
--- /dev/null
+++ b/doc/administration/upgrading.rst
@@ -0,0 +1,67 @@
+Upgrading
+=========
+
+Fietsboek does not currently have an automated updater, however it is quite
+simple to update Fietsboek manually.
+
+.. warning::
+
+    Make sure to have backups of your user data ready in case the upgrade fails!
+
+.. note::
+
+    It is advised to stop the Fietsboek server during the backup process.
+
+Pulling the New Code
+--------------------
+
+First, we need to pull the new code. This step depends on the source that you
+have installed Fietsboek from. In the case that you use ``git``, this can be
+done in the following way:
+
+.. code:: bash
+
+    git pull
+    git checkout v42.0  # Put in the version that you want to update to here
+
+If you have downloaded an archive with the Fietsboek source, you need to
+download the archive with the new version and extract it somewhere.
+
+Installing the Python Module
+----------------------------
+
+Use ``pip`` to install the new version of the Fietsboek package, as well as any
+new additional dependencies:
+
+.. code:: bash
+
+    .venv/bin/pip install .
+
+This step is similar to the command that you used when installing Fietsboek
+initially.
+
+Note that removed dependencies are not automatically removed. It might be worth
+to start with a clean virtual environment from time to time to clear out old
+cruft.
+
+Upgrading the Database
+----------------------
+
+.. warning::
+
+   It cannot be stressed enough that you should have backups of your data. This
+   is your last chance.
+
+Some updates might change the database schema. Those updates come with database
+migrations that can adapt an existing database to the new schema. In order to
+do so, use ``alembic``:
+
+.. code:: bash
+
+    .venv/bin/alembic -c production.ini upgrade head
+
+Restarting Fietsboek
+--------------------
+
+You can now run Fietsboek again. This step depends on the method that you use
+to deploy Fietsboek.
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..e7f04e0
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Fietsboek'
+copyright = '2022, Daniel Schadt'
+author = 'Daniel Schadt'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'pyramid': ('https://docs.pylonsproject.org/projects/pyramid/en/latest/', None),
+    'sqlalchemy': ('https://docs.sqlalchemy.org/en/14/', None),
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..05449cd
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,46 @@
+.. Fietsboek documentation master file, created by
+   sphinx-quickstart on Thu Jun 30 20:46:28 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Fietsboek's documentation!
+=====================================
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    administration/installation
+    administration/configuration
+    administration/upgrading
+    administration/backup
+
+Fietsboek is a self-hostable sharing site for GPX track recordings with social
+features. The goal is to have an application like `MyTourbook
+<https://mytourbook.sourceforge.io/mytourbook/>`__ that runs as a web-service
+and allows sharing and discovering of new tracks.
+
+This documentation contains content pertaining to the installation, maintenance
+and administration of a Fietsboek setup. Documentation about using Fietsboek
+and extending/modifying Fietsboek will follow in the future.
+
+Fietsboek is `FLOSS
+<https://en.wikipedia.org/wiki/Free_and_open-source_software>`__, licensed
+under the `AGPLv3 license <https://www.gnu.org/licenses/agpl-3.0.en.html>`__.
+Fietsboek is built on top of the following open source technologies:
+
+* `Pyramid <https://trypyramid.com/>`__
+* `gpxpy <https://pypi.org/project/gpxpy/>`__
+* Jürgen Berkemeier's `GPXViewer <https://www.j-berkemeier.de/GPXViewer/>`__
+* `OpenStreetMap <https://www.openstreetmap.org/>`__
+* `Bootstrap <https://getbootstrap.com/>`__ and `Bootstrap Icons
+  <https://icons.getbootstrap.com/>`__
+* `OpenSans <https://github.com/googlefonts/opensans>`__ (Copyright 2020 The
+  Open Sans Project Authors)
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/make.bat b/doc/make.bat
new file mode 100644
index 0000000..32bb245
--- /dev/null
+++ b/doc/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF

+

+pushd %~dp0

+

+REM Command file for Sphinx documentation

+

+if "%SPHINXBUILD%" == "" (

+	set SPHINXBUILD=sphinx-build

+)

+set SOURCEDIR=.

+set BUILDDIR=_build

+

+%SPHINXBUILD% >NUL 2>NUL

+if errorlevel 9009 (

+	echo.

+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx

+	echo.installed, then set the SPHINXBUILD environment variable to point

+	echo.to the full path of the 'sphinx-build' executable. Alternatively you

+	echo.may add the Sphinx directory to PATH.

+	echo.

+	echo.If you don't have Sphinx installed, grab it from

+	echo.https://www.sphinx-doc.org/

+	exit /b 1

+)

+

+if "%1" == "" goto help

+

+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

+goto end

+

+:help

+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

+

+:end

+popd