Add initial docs
This commit is contained in:
Lance Edgar
parent
7e3b38aaee
commit
e2445d07ab
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -1 +1,2 @@
|
|||
Messkit.egg-info/
|
||||
docs/_build/
|
||||
|
|
|
|||
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
|
|
@ -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)
|
||||
60
docs/conf.py
Normal file
60
docs/conf.py
Normal file
|
|
@ -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 = 'Messkit'
|
||||
copyright = '2022, Lance Edgar'
|
||||
author = 'Lance Edgar'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '0.1'
|
||||
|
||||
|
||||
# -- 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.intersphinx',
|
||||
]
|
||||
|
||||
intersphinx_mapping = {
|
||||
'rattail-manual': ('https://rattailproject.org/docs/rattail-manual/', 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']
|
||||
88
docs/features.rst
Normal file
88
docs/features.rst
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
|
||||
Features
|
||||
========
|
||||
|
||||
This page lists the "completed" features for Messkit. All of the
|
||||
following are considered working and stable.
|
||||
|
||||
Also note, here we only highlight features deemed Messkit-specific.
|
||||
Since Messkit is built on top of lots of other tech, there are `many
|
||||
more features`_ which have been complete for years. Most of those
|
||||
underlying features assumed a programmer would "glue" components
|
||||
together in code, whereas Messkit is trying to let the admin user do
|
||||
that via web app instead. So this feature list reflects only the
|
||||
Messkit-specific goals.
|
||||
|
||||
.. _`many more features`: https://rattailproject.org/moin/TheBigTour
|
||||
|
||||
|
||||
Configurable Menus
|
||||
------------------
|
||||
|
||||
Nearly the entire top-level menu is editable. The "user" menu (far
|
||||
right of top menu) is *not* editable, but all other top-level menus
|
||||
are "fully" editable.
|
||||
|
||||
(More complexity should be allowed yet, e.g. adding a submenu, but the
|
||||
common needs are met already.)
|
||||
|
||||
Go to the App Settings page (/settings/app/) and from the "Go To
|
||||
Configure" dropdown choose Menus.
|
||||
|
||||
|
||||
Configurable Views
|
||||
------------------
|
||||
|
||||
This is related to the previous point (e.g. a menu entry usually
|
||||
references some sort of view), but is definitely a separate concern.
|
||||
|
||||
First to clarify.. A "view" in this context really means a "Python
|
||||
module containing view logic" and that "view logic" is what responds
|
||||
to user requests and displays data etc. Most often a particular view
|
||||
is tied to a particular table in the DB.
|
||||
|
||||
Messkit comes with many views built-in, but not all will be relevant
|
||||
to you. For instance you might need to see Employees but not
|
||||
Products.
|
||||
|
||||
Messkit allows for any such built-in view to be:
|
||||
|
||||
* disabled
|
||||
* enabled, using default view module
|
||||
* enabled, using custom view module
|
||||
|
||||
Go to the App Settings page (/settings/app/) and from the "Go To
|
||||
Configure" dropdown choose Included Views.
|
||||
|
||||
|
||||
Custom Reports
|
||||
--------------
|
||||
|
||||
Messkit comes with "some" reports built-in. However there are very
|
||||
few and they serve mostly as examples.
|
||||
|
||||
First to clarify, a "report" in this context really means a "Python
|
||||
module containing report logic" and that "report logic" is what
|
||||
generates the output file.
|
||||
|
||||
Messkit allows you to create new reports (Python modules) to suit your
|
||||
needs. Reporting needs can vary wildly, so Messkit does not try to
|
||||
provide the full interface to create a "complete" detailed report.
|
||||
But it can generate some skeleton code and get you started in the
|
||||
right direction.
|
||||
|
||||
More "flavors" of sample code generation should be added, but there
|
||||
are some basic ones in place already. Namely they allow for either
|
||||
using raw SQL to query tables, or alternately can use the SQLAlchemy
|
||||
models which then auto-generate the SQL needed.
|
||||
|
||||
At this time Messkit does not have any smarts about "other systems"
|
||||
and therefore sample code it generates will only show how to query the
|
||||
Messkit database. As time goes on more sample code will be added,
|
||||
which shows how to query other (e.g. POS) databases, as well as e.g.
|
||||
web API for some systems.
|
||||
|
||||
Messkit "blends" the custom reports with its built-in reports, in the
|
||||
user interface. Meaning, if a user goes to generate a new report
|
||||
(i.e. run a module to produce output) then they will see all available
|
||||
reports in the same list.
|
||||
37
docs/index.rst
Normal file
37
docs/index.rst
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
|
||||
Messkit
|
||||
=======
|
||||
|
||||
Got a mess goin' on? There's a kit for that...
|
||||
|
||||
Messkit aims to be a "custom app in a box" for operational data
|
||||
management, automation etc. Sort of like a spreadsheet on sterroids,
|
||||
where the user defines the data layout and behavior as much as
|
||||
possible.
|
||||
|
||||
It comes with several tables to store commonly-needed data, but the
|
||||
goal is to provide an easy interface to add extra tables (and
|
||||
importers!) etc. as needed.
|
||||
|
||||
For now Messkit is very much a work in progress! But nearly all of
|
||||
the underlying tech has been in production for years, so is quite
|
||||
stable. Installation is quick and painless (as is upgrading) so get
|
||||
started today and enjoy the evolution...
|
||||
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
install
|
||||
features
|
||||
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
157
docs/install.rst
Normal file
157
docs/install.rst
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
|
||||
.. highlight:: sh
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
We'll try to keep this brief but link to further reading where needed.
|
||||
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* Linux strongly recommended
|
||||
* Python 3
|
||||
* database in PostgreSQL or MySQL (or ??)
|
||||
|
||||
Linux is recommended because effectively "all" production testing has
|
||||
happened on Debian and Ubuntu specifically. But the project is all
|
||||
Python so should run anywhere as long as the code is accounting for
|
||||
that...which to be honest it may not be in all places yet.
|
||||
|
||||
The assumption is that you already have Python 3, unless on Windows in
|
||||
which case see :doc:`rattail-manual:base/install/windows/python`.
|
||||
|
||||
You can ostensibly use any backend `supported by SQLAlchemy`_ to store
|
||||
your Messkit database; however in practice PostgreSQL has had a
|
||||
gazillion times more production testing and is highly recommended.
|
||||
MySQL/MariaDB also have seen some basic testing and are believed to
|
||||
work fine.
|
||||
|
||||
.. _`supported by SQLAlchemy`: https://docs.sqlalchemy.org/en/13/dialects/index.html
|
||||
|
||||
Note that the database need not live on the same machine as the
|
||||
Messkit app.
|
||||
|
||||
The Messkit installer currently only supportes PostgreSQL and
|
||||
MySQL/MariaDB, so if another backend is desired it just means the
|
||||
installer can't automate setup for you, but manual setup is still
|
||||
possible.
|
||||
|
||||
|
||||
Messkit
|
||||
-------
|
||||
|
||||
Create a virtual environment for Messkit, e.g.::
|
||||
|
||||
python3 -m venv /path/to/envs/messkit
|
||||
|
||||
If you're new to these see also :doc:`rattail-manual:base/venv`.
|
||||
|
||||
Be sure to activate your virtual environment::
|
||||
|
||||
source /path/to/envs/messkit/bin/activate
|
||||
|
||||
Next install the Messkit package to your environment::
|
||||
|
||||
pip install Messkit
|
||||
|
||||
Now setup your database backend. Messkit will need a database, and it
|
||||
will need to connect to that database with a particular set of user
|
||||
credentials.
|
||||
|
||||
Depending on your backend type, create the user account. The default
|
||||
username is ``rattail`` so we'll assume that here. Whatever username
|
||||
and password you set will be needed for the final Messkit setup.
|
||||
|
||||
PostgreSQL::
|
||||
|
||||
sudo -u postgres createuser -P rattail
|
||||
|
||||
MySQL::
|
||||
|
||||
sudo mysql -e "create user rattail@localhost"
|
||||
sudo mysql -e "alter user rattail@localhost identified by 'THEPASSWORD'"
|
||||
|
||||
Next create the database itself.
|
||||
|
||||
PostgreSQL::
|
||||
|
||||
sudo -u postgres createdb -O rattail messkit
|
||||
|
||||
MySQL::
|
||||
|
||||
sudo mysqladmin create messkit
|
||||
sudo mysql -e "grant all on messkit.* to rattail@localhost"
|
||||
|
||||
Finally run the Messkit installer. When it asks for **db type** you
|
||||
can enter ``mysql`` or just accept the ``postgresql`` default. You
|
||||
are advised to answer "yes" to all yes/no questions::
|
||||
|
||||
messkit -n install
|
||||
|
||||
With that complete you should be able to run the web app with::
|
||||
|
||||
cd /path/to/envs/messkit
|
||||
bin/pserve file+ini:app/web.conf
|
||||
|
||||
Please note, you should have created an admin user during the Messkit
|
||||
installer. You should be able to login to the web app with those
|
||||
credentials, but by default even an "admin" user can't do much of
|
||||
anything.
|
||||
|
||||
However an admin user has a special power - they can "become root"
|
||||
which means the same as it does for Linux. When you do this all
|
||||
features which exist become unlocked. The expectation for a
|
||||
"production" app is that you would define roles and grant them
|
||||
permissions etc. as needed. But while testing you can just "become
|
||||
root" and not really worry about the permissions.
|
||||
|
||||
|
||||
Upgrading
|
||||
---------
|
||||
|
||||
Upgrades are done directly in the web app, and basic details of each
|
||||
are recorded.
|
||||
|
||||
Default menu location is Admin -> Messkit Upgrades. Create a new
|
||||
upgrade, make sure it is enabled, then execute it. That's all!
|
||||
|
||||
Although, the default upgrade script will not actually restart the web
|
||||
app for you, so after an upgrade completes successfully you should
|
||||
restart the web app manually.
|
||||
|
||||
|
||||
Starting Over
|
||||
-------------
|
||||
|
||||
A major goal for Messkit is to make "starting over" a simple thing, to
|
||||
encourage users to experiment with it. Maybe you even keep one app in
|
||||
production while having others reserved for trying new things.
|
||||
|
||||
The installer is of course a big part of that, so hopefully it's easy
|
||||
enough, but suggestions for improvements are always welcome!
|
||||
|
||||
But depending on your situation you may prefer to "destroy" the
|
||||
previous attempt before installing a new app etc. Really that is just
|
||||
2 steps:
|
||||
|
||||
Remove entirely your "app" folder, e.g.::
|
||||
|
||||
cd /path/to/envs/messkit
|
||||
rm -rf app
|
||||
|
||||
Then drop and re-create your database. Commands for creating a
|
||||
database are shown above, but here are the drops.
|
||||
|
||||
PostgreSQL::
|
||||
|
||||
sudo -u postgres dropdb messkit
|
||||
|
||||
MySQL::
|
||||
|
||||
sudo mysqladmin drop messkit
|
||||
|
||||
With that done you can re-run the installer::
|
||||
|
||||
messkit -n install
|
||||
35
docs/make.bat
Normal file
35
docs/make.bat
Normal file
|
|
@ -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
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%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
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
Loading…
Reference in a new issue