From e2445d07abd9965cae2a82999dfaaf6b754da49a Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Sat, 5 Mar 2022 14:50:00 -0600 Subject: [PATCH] Add initial docs --- .gitignore | 1 + docs/Makefile | 20 ++++++ docs/conf.py | 60 ++++++++++++++++++ docs/features.rst | 88 ++++++++++++++++++++++++++ docs/index.rst | 37 +++++++++++ docs/install.rst | 157 ++++++++++++++++++++++++++++++++++++++++++++++ docs/make.bat | 35 +++++++++++ setup.py | 1 + 8 files changed, 399 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/features.rst create mode 100644 docs/index.rst create mode 100644 docs/install.rst create mode 100644 docs/make.bat diff --git a/.gitignore b/.gitignore index 212ca21..b26036a 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ Messkit.egg-info/ +docs/_build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..3d2fb0b --- /dev/null +++ b/docs/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 = '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'] diff --git a/docs/features.rst b/docs/features.rst new file mode 100644 index 0000000..2703c29 --- /dev/null +++ b/docs/features.rst @@ -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. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..a722519 --- /dev/null +++ b/docs/index.rst @@ -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` diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..5fdd701 --- /dev/null +++ b/docs/install.rst @@ -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 diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..153be5e --- /dev/null +++ b/docs/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 + +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 diff --git a/setup.py b/setup.py index fb02cef..cd574b4 100644 --- a/setup.py +++ b/setup.py @@ -68,6 +68,7 @@ requires = [ 'prompt_toolkit', # 3.0.28 'rich', # 11.2.0 + 'Sphinx', # 4.4.0 'Tailbone', # 0.8.206 ]