Add more install docs

docs/conf.py

@@ -26,6 +26,7 @@ templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 intersphinx_mapping = {
+    'packaging': ('https://packaging.python.org/en/latest/', None),
     'python': ('https://docs.python.org/3/', None),
     'python-configuration': ('https://python-configuration.readthedocs.io/en/latest/', None),
     'rattail': ('https://rattailproject.org/docs/rattail/', None),

docs/glossary.rst

@@ -91,7 +91,8 @@ Glossary
 
    package
      Generally refers to a proper Python package, i.e. a collection of
-     modules etc. which is installed via ``pip``.
+     modules etc. which is installed via ``pip``.  See also
+     :doc:`narr/install/pkg`.
 
    settings table
      Table in the :term:`app database` which is used to store
@@ -102,4 +103,9 @@ Glossary
      A top-level :term:`command` may expose one or more subcommands,
      for the overall command line interface.  Subcommands are the real
      workhorse; each can perform a different function.  See also
-     :class:`~wuttjamaican.cmd.base.Subcommand`.
+     :doc:`narr/cli/subcommands`.
+
+   virtual environment
+     This term comes from the broader Python world and refers to an
+     isolated way to install :term:`packages<package>`.  See also
+     :doc:`narr/install/venv`.

docs/narr/install/index.rst

@@ -8,3 +8,6 @@ Read on for setup instructions etc.
    :maxdepth: 2
 
    quickstart
+   prereqs
+   venv
+   pkg

docs/narr/install/pkg.rst

@@ -0,0 +1,21 @@
+
+Package Installation
+====================
+
+To install the :term:`package` into your :term:`virtual environment`:
+
+.. code-block:: sh
+
+   pip install WuttJamaican
+
+Please also see
+:doc:`packaging:guides/installing-using-pip-and-virtual-environments`
+in upstream docs.
+
+
+Sanity Check
+------------
+
+Confirm that worked with:
+
+.. command-output:: wutta --version

docs/narr/install/prereqs.rst

@@ -0,0 +1,36 @@
+
+Prerequisites
+=============
+
+Wuttjamaican requires Python, and optionally a database of some sort.
+
+
+Python
+------
+
+Currently at least Python 3.6 is required, however:
+
+As of writing only Python 3.8 and newer are supported by the official
+Python team, so that is strongly recommended.  It is likely that will
+soon become the minimum requirement for WuttJamaican as well.
+
+Also note, Python 3.11 is the newest version being tested so far.
+
+See also https://endoflife.date/python
+
+
+Database
+--------
+
+There is not yet much logic in WuttJamaican which pertains to the
+:term:`app database` so we will not document much about that here
+either.
+
+For now just know that in a production environment, PostgreSQL is
+recommended for the DB backend.  So install that if you want to be
+certain of a good experience.
+
+But technically speaking, anything supported by `SQLAlchemy`_ should
+work.  See also :doc:`/narr/config/table`.
+
+.. _SQLAlchemy: https://www.sqlalchemy.org

docs/narr/install/venv.rst

@@ -0,0 +1,44 @@
+
+Virtual Environment
+===================
+
+Regardless of platform, you are strongly encouraged to use a
+:term:`virtual environment` for your :term:`app`.  This allows you to
+experiment with installation without affecting the rest of your
+system.
+
+See also the upstream definition for :term:`packaging:Virtual
+Environment`.
+
+
+Choosing a Location
+-------------------
+
+It can be helpful to standardize the location of all your virtual
+environments regardless of their purpose.  The tool you use to create
+a virtual environment may or may not have opinions on where that
+should be.
+
+WuttJamaican should not assume anything as far as where the virtual
+environments live.  But if you have no preference you might consider:
+
+* Linux - ``/srv/envs``
+* Windows - ``C:\envs``
+
+So for instance if you run Linux and make a new virtual environment
+named ``poser`` then it would live in ``/srv/envs/poser`` according to
+the above.
+
+
+Creating a Virtual Environment
+------------------------------
+
+For our purposes, on Linux you can do this:
+
+.. code-block:: sh
+
+   python3 -m venv /srv/envs/poser
+
+Please also see
+:doc:`packaging:guides/installing-using-pip-and-virtual-environments`
+in upstream docs.