Add user manual (#111)

.gitignore

@@ -29,3 +29,6 @@ yarn-error.log
 .phpunit.result.cache
 /phpunit.xml
 ###< symfony/phpunit-bridge ###
+
+docs/_build/
+

.readthedocs.yaml

@@ -0,0 +1,13 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf

composer.json

@@ -99,6 +99,9 @@
             "cache:clear": "symfony-cmd",
             "assets:install %PUBLIC_DIR%": "symfony-cmd"
         },
+        "docs": [
+            "cd docs && make html SPHINXOPTS=\"-W\""
+        ],
         "test": [
             "composer validate",
             "composer normalize --dry-run",

docs/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)

docs/conf.py

@@ -0,0 +1,29 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# Docs: https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+
+project = 'Twyne'
+copyright = '2021, Sam Wilson'
+author = 'Sam Wilson'
+
+# Read the version numbers from the latest Git tag.
+import os
+import re
+release = os.popen('git describe --tags --always').read().strip()
+version = release
+
+extensions = []
+
+# 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 -------------------------------------------------
+html_theme = 'sphinx_rtd_theme'
+html_show_copyright = False
+html_static_path = ['_static']

docs/config.rst

@@ -0,0 +1,15 @@
+.. _config:
+
+Configuration
+=============
+
+All the important parts of configuration of a Twyne site
+happen in the ``.env.local`` file::
+
+    APP_SECRET=a-long-random-string
+    APP_MAIL_SENDER=admin@example.org
+    APP_LOG_RECIPIENT=admin@example.org
+    MAILER_DSN=smtp://username:password@smtp.gmail.com
+
+Other configuration happens on the Settings page,
+accessible via the main menu.

docs/index.rst

@@ -0,0 +1,29 @@
+Twyne: an indieweb blogging CMS
+===============================
+
+Welcome to the **user manual for Twyne**,
+an open-source web-based content management system
+that is based around the traditional blog format of
+chronological posts that can contain writing, photographs, and lots of metadata.
+Twyne aims to operate within the `indieweb`_,
+a philosophy of website architecture that prioritises
+openness, interoperability, and a sense of personal control
+for people running their own websites.
+
+This user manual is aimed at people running Twyne for their own websites.
+It covers installation, configuration, and general usage.
+Any questions about anything in here
+should be asked on the `issue tracker`_ on Github
+(to do this, you will need a Github user account, which is free).
+For any question that you ask,
+we will endevour to fix up the manual to make it clearer about that topic.
+
+.. _`indieweb`: https://indieweb.org/
+.. _`issue tracker`: https://github.com/samwilson/twyne/issues
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   install
+   config

docs/install.rst

@@ -0,0 +1,74 @@
+Installing and upgrading
+========================
+
+Prerequesites
+-------------
+
+To install Twyne, you need the following:
+
+1. a web server with PHP 7.3 or above;
+2. command-line access to that server;
+3. the `Git`_ version control system; and
+4. the PHP package manager, `Composer`_.
+
+.. _`Git`: https://git-scm.com/
+.. _`Composer`: https://getcomposer.org/
+
+Downloading
+-----------
+
+First, clone the latest version of the source code
+into a non web-accessible location on your server::
+
+    git clone https://github.com/samwilson/twyne.git /var/www/twyne
+
+Create a new database and grant access to it to a new user.
+Add the details of this database and the user's credentials
+to the ``.env.local`` file in the ``DATABASE_URL`` key::
+
+    DATABASE_URL=mysql://user_name:password@127.0.0.1:3306/db_name
+
+Then install the application with the included script,
+which checks out the latest version and installs all dependencies with Composer::
+
+    /var/www/twyne/bin/deploy.sh prod /var/www/twyne
+
+Next, set up your web server to serve the ``public/`` directory
+as the root of the new web site.
+For Apache, this could be something like the following::
+
+    <VirtualHost *:80>
+        ServerName example.org
+        RewriteRule ^/(.*)$ https://example.org/$1 [L,R=permanent,QSA]
+    </VirtualHost>
+    <VirtualHost *:80>
+        ServerName www.example.org
+        RewriteRule ^/(.*)$ https://example.org/$1 [L,R=permanent,QSA]
+    </VirtualHost>
+    <VirtualHost *:443>
+        ServerName example.org
+        DocumentRoot /var/www/twyne/public/
+        SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
+        <Directory "/var/www/twyne/public/">
+            RewriteRule ^index\.php$ - [L]
+            RewriteCond %{REQUEST_FILENAME} !-f
+            RewriteCond %{REQUEST_FILENAME} !-d
+            RewriteRule . /index.php [L]
+        </Directory>
+    </VirtualHost>
+
+Where ``example.org`` is replaced by your own domain name.
+
+Your new Twyne site should now be live.
+Navigate to the home page,
+and continue the set-up process as detailed in the :ref:`config` section of this manual.
+
+Upgrading
+---------
+
+Upgrading is as simple as re-running the ``deploy.sh`` script.
+This will checkout the latest version of the code,
+install dependencies,
+and update the database as required.
+This script can be run automatically on a daily or weekly basis
+(as a Cronjob or Scheduled Task, for instance).

phpcs.xml.dist

@@ -17,5 +17,6 @@
     <exclude-pattern>public/build/</exclude-pattern>
     <exclude-pattern>./bin/.phpunit/</exclude-pattern>
     <exclude-pattern>*.js</exclude-pattern>
+    <exclude-pattern>docs/_build/</exclude-pattern>
 
 </ruleset>