docs: add initial docs, w/ quickstart

just the very basics to get things in place
This commit is contained in:
Lance Edgar 2024-07-09 21:05:59 -05:00
parent e2e4df4721
commit 717f9518ff
9 changed files with 184 additions and 0 deletions

1
.gitignore vendored
View file

@ -2,4 +2,5 @@
*.pyc
WuttaPOS.egg-info/
dist/
docs/_build/
wuttapos/assets/custom_header_logo.png

20
docs/Makefile Normal file
View 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)

0
docs/_static/.keepme vendored Normal file
View file

30
docs/conf.py Normal file
View file

@ -0,0 +1,30 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
from importlib.metadata import version as get_version
project = 'WuttaPOS'
copyright = '2024, Lance Edgar'
author = 'Lance Edgar'
release = get_version('WuttaPOS')
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = []
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'furo'
html_static_path = ['_static']

17
docs/index.rst Normal file
View file

@ -0,0 +1,17 @@
WuttaPOS
========
.. toctree::
:maxdepth: 2
:caption: Contents:
quickstart
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

35
docs/make.bat Normal file
View 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
%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

71
docs/quickstart.rst Normal file
View file

@ -0,0 +1,71 @@
=============
Quick Start
=============
.. highlight:: sh
WuttaPOS is a `Python`_ app based on `Rattail`_.
.. _Python: https://www.python.org/
.. _Rattail: https://rattailproject.org/
As such it requires a Rattail DB to already be established, containing
data for users (cashiers), customers, products etc. Getting all that
setup is outside the scope of this guide; for more info see the
`Rattail Manual`_.
.. _Rattail Manual: https://rattailproject.org/docs/rattail-manual/
Here we are focused only on getting the WuttaPOS app setup.
Installation
------------
Make a virtual environment::
python -m venv /srv/envs/wuttapos
Install the WuttaPOS package into it::
cd /srv/envs/wuttapos
bin/pip install WuttaPOS
Configuration
-------------
Make a basic config file::
cd /srv/envs/wuttapos
bin/rattail make-config -T rattail -O app
Then edit ``app/rattail.conf`` to suit your needs. In particular you
must specify the DB connection.
Usage
-----
Now you can run the app::
cd /srv/envs/wuttapos
bin/wuttapos open
Access Control
--------------
Note that the app will only allow a user to login to POS, if they have
permissions specific to the POS, namely "ring sales"
(``pos.ring_sales``).
Once logged in, additional POS-specific permissions will determine
whether the user may perform some actions, or not. In the latter case
the user may *initiate* the action but then another user
(e.g. manager) must login to complete the action.
All permissions must be managed externally, e.g. via your Rattail
back-office web app. WuttaPOS will honor them but does not expose a
way to manage them.

View file

@ -33,6 +33,10 @@ dependencies = [
]
[project.optional-dependencies]
docs = ["Sphinx", "furo"]
[project.scripts]
wuttapos = "wuttapos.commands:wuttapos_typer"

6
tox.ini Normal file
View file

@ -0,0 +1,6 @@
[testenv:docs]
basepython = python3.11
extras = docs
changedir = docs
commands = sphinx-build -b html -d {envtmpdir}/doctrees -W -T . {envtmpdir}/docs