From da9823324d0c213ae82ad010d24f0480d6979104 Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Fri, 15 Jan 2021 15:16:23 -0600 Subject: [PATCH] More docs! w/ some emphasis on "reports" section --- docs/base/cron.rst | 11 ++++ docs/base/email.rst | 53 ------------------ docs/base/email/bounces.rst | 6 +++ docs/base/email/code.rst | 5 ++ docs/base/email/config.rst | 16 ++++++ docs/base/email/dev.rst | 8 +++ docs/base/email/handler.rst | 6 +++ docs/base/email/index.rst | 18 +++++++ docs/base/email/logging.rst | 6 +++ docs/base/email/overview.rst | 24 +++++++++ docs/base/email/postfix.rst | 5 ++ docs/base/email/system.rst | 5 ++ docs/base/email/templates.rst | 6 +++ docs/base/handlers.rst | 2 + docs/base/index.rst | 4 +- docs/base/upgrades.rst | 6 +++ docs/conf.py | 5 ++ docs/data/batch/custom.rst | 6 +++ docs/data/batch/handlers.rst | 6 +++ docs/data/batch/index.rst | 13 +++++ docs/data/batch/native.rst | 6 +++ docs/data/batch/overview.rst | 6 +++ docs/data/batch/schema.rst | 6 +++ docs/data/batches.rst | 5 -- docs/data/datasync.rst | 5 -- docs/data/index.rst | 6 ++- docs/data/problems.rst | 5 ++ docs/data/reports/autoemail.rst | 6 +++ docs/data/reports/custom.rst | 81 ++++++++++++++++++++++++++++ docs/data/reports/generate.rst | 6 +++ docs/data/reports/handler.rst | 19 +++++++ docs/data/reports/index.rst | 13 +++++ docs/data/reports/overview.rst | 28 ++++++++++ docs/data/sync.rst | 5 ++ docs/index.rst | 11 ++-- docs/{luigi => monitor}/index.rst | 5 +- docs/{luigi => monitor}/overview.rst | 0 docs/monitor/shinken.rst | 5 ++ 38 files changed, 358 insertions(+), 71 deletions(-) create mode 100644 docs/base/cron.rst delete mode 100644 docs/base/email.rst create mode 100644 docs/base/email/bounces.rst create mode 100644 docs/base/email/code.rst create mode 100644 docs/base/email/config.rst create mode 100644 docs/base/email/dev.rst create mode 100644 docs/base/email/handler.rst create mode 100644 docs/base/email/index.rst create mode 100644 docs/base/email/logging.rst create mode 100644 docs/base/email/overview.rst create mode 100644 docs/base/email/postfix.rst create mode 100644 docs/base/email/system.rst create mode 100644 docs/base/email/templates.rst create mode 100644 docs/base/upgrades.rst create mode 100644 docs/data/batch/custom.rst create mode 100644 docs/data/batch/handlers.rst create mode 100644 docs/data/batch/index.rst create mode 100644 docs/data/batch/native.rst create mode 100644 docs/data/batch/overview.rst create mode 100644 docs/data/batch/schema.rst delete mode 100644 docs/data/batches.rst delete mode 100644 docs/data/datasync.rst create mode 100644 docs/data/problems.rst create mode 100644 docs/data/reports/autoemail.rst create mode 100644 docs/data/reports/custom.rst create mode 100644 docs/data/reports/generate.rst create mode 100644 docs/data/reports/handler.rst create mode 100644 docs/data/reports/index.rst create mode 100644 docs/data/reports/overview.rst create mode 100644 docs/data/sync.rst rename docs/{luigi => monitor}/index.rst (60%) rename docs/{luigi => monitor}/overview.rst (100%) create mode 100644 docs/monitor/shinken.rst diff --git a/docs/base/cron.rst b/docs/base/cron.rst new file mode 100644 index 0000000..d093f42 --- /dev/null +++ b/docs/base/cron.rst @@ -0,0 +1,11 @@ + +Scheduled Tasks +=============== + +TODO + + +Luigi +----- + +TODO diff --git a/docs/base/email.rst b/docs/base/email.rst deleted file mode 100644 index 1c1bf29..0000000 --- a/docs/base/email.rst +++ /dev/null @@ -1,53 +0,0 @@ - -Sending Email -============= - -TODO - - -Postfix Setup -------------- - -TODO - - -Types of Emails ---------------- - -TODO - - -Configuring SMTP ----------------- - -TODO - - -Configuring Recipients etc. ---------------------------- - -TODO - - -Customizing Templates ---------------------- - -TODO - - -How to programmatically send email ----------------------------------- - -TODO - - -Nod to email via error logging ------------------------------- - -TODO - - -Handling Email Bounces ----------------------- - -TODO diff --git a/docs/base/email/bounces.rst b/docs/base/email/bounces.rst new file mode 100644 index 0000000..3da38db --- /dev/null +++ b/docs/base/email/bounces.rst @@ -0,0 +1,6 @@ + +======================== + Handling Email Bounces +======================== + +TODO diff --git a/docs/base/email/code.rst b/docs/base/email/code.rst new file mode 100644 index 0000000..37c7171 --- /dev/null +++ b/docs/base/email/code.rst @@ -0,0 +1,5 @@ + +Programmatically Sending Email +------------------------------ + +TODO diff --git a/docs/base/email/config.rst b/docs/base/email/config.rst new file mode 100644 index 0000000..79e0893 --- /dev/null +++ b/docs/base/email/config.rst @@ -0,0 +1,16 @@ + +Rattail Configuration +===================== + +TODO + +Configuring SMTP +---------------- + +TODO + + +Configuring Recipients etc. +--------------------------- + +TODO diff --git a/docs/base/email/dev.rst b/docs/base/email/dev.rst new file mode 100644 index 0000000..980b071 --- /dev/null +++ b/docs/base/email/dev.rst @@ -0,0 +1,8 @@ + +---------------------------- + Development Considerations +---------------------------- + +TODO + +* aka. how not to send unwanted/test emails to staff or public! diff --git a/docs/base/email/handler.rst b/docs/base/email/handler.rst new file mode 100644 index 0000000..53d215b --- /dev/null +++ b/docs/base/email/handler.rst @@ -0,0 +1,6 @@ + +=============== + Email Handler +=============== + +TODO diff --git a/docs/base/email/index.rst b/docs/base/email/index.rst new file mode 100644 index 0000000..f08afe6 --- /dev/null +++ b/docs/base/email/index.rst @@ -0,0 +1,18 @@ + +Sending Email +============= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + postfix + system + logging + config + templates + code + handler + dev + bounces diff --git a/docs/base/email/logging.rst b/docs/base/email/logging.rst new file mode 100644 index 0000000..50680a7 --- /dev/null +++ b/docs/base/email/logging.rst @@ -0,0 +1,6 @@ + +================ +Logging to Email +================ + +TODO diff --git a/docs/base/email/overview.rst b/docs/base/email/overview.rst new file mode 100644 index 0000000..ce674ce --- /dev/null +++ b/docs/base/email/overview.rst @@ -0,0 +1,24 @@ + +========== + Overview +========== + +This manual is primarily concerned with 3 "types" of email: + +* emails sent by the underlying system +* emails sent via Python logging mechanism +* emails sent explicitly by a Poser/Rattail app + +The first, "emails sent by the underlying system" refers primarily to emails +sent by the ``cron`` daemon. See :doc:`system` for more about those. + +The second, "emails sent via Python logging mechanism" is covered in +:doc:`logging`. + +The third, "emails sent explicitly by a Poser/Rattail app" is the primary +motivation behind this section of the manual. In particular see the sections +about :doc:`config`, :doc:`templates` and :doc:`code`. + +Finally, if you're sending email to the public, it may be helpful to detect +bounces and e.g. flag an address as invalid if it triggers a bounce. See +:doc:`bounces` for more on that. diff --git a/docs/base/email/postfix.rst b/docs/base/email/postfix.rst new file mode 100644 index 0000000..3d1b1d3 --- /dev/null +++ b/docs/base/email/postfix.rst @@ -0,0 +1,5 @@ + +Postfix Setup +============= + +TODO diff --git a/docs/base/email/system.rst b/docs/base/email/system.rst new file mode 100644 index 0000000..c426ee3 --- /dev/null +++ b/docs/base/email/system.rst @@ -0,0 +1,5 @@ + +System Emails +============= + +TODO diff --git a/docs/base/email/templates.rst b/docs/base/email/templates.rst new file mode 100644 index 0000000..5b3a377 --- /dev/null +++ b/docs/base/email/templates.rst @@ -0,0 +1,6 @@ + +======================= + Customizing Templates +======================= + +TODO diff --git a/docs/base/handlers.rst b/docs/base/handlers.rst index 4993d69..b411cc4 100644 --- a/docs/base/handlers.rst +++ b/docs/base/handlers.rst @@ -3,3 +3,5 @@ App Handlers ============ TODO + +* Report Handler diff --git a/docs/base/index.rst b/docs/base/index.rst index c92eb39..92a4ff5 100644 --- a/docs/base/index.rst +++ b/docs/base/index.rst @@ -13,7 +13,9 @@ Base Layer config/index commands scripts - email + email/index + cron supervisor filemon + upgrades handlers diff --git a/docs/base/upgrades.rst b/docs/base/upgrades.rst new file mode 100644 index 0000000..e0bcf5c --- /dev/null +++ b/docs/base/upgrades.rst @@ -0,0 +1,6 @@ + +============== + App Upgrades +============== + +TODO diff --git a/docs/conf.py b/docs/conf.py index e46575d..ce60e26 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,8 +33,13 @@ author = 'Lance Edgar' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.intersphinx', ] +intersphinx_mapping = { + 'rattail': ('https://rattailproject.org/docs/rattail/', None), +} + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/data/batch/custom.rst b/docs/data/batch/custom.rst new file mode 100644 index 0000000..0ccf7ce --- /dev/null +++ b/docs/data/batch/custom.rst @@ -0,0 +1,6 @@ + +===================== +Adding a Custom Batch +===================== + +TODO diff --git a/docs/data/batch/handlers.rst b/docs/data/batch/handlers.rst new file mode 100644 index 0000000..2795399 --- /dev/null +++ b/docs/data/batch/handlers.rst @@ -0,0 +1,6 @@ + +============== +Batch Handlers +============== + +TODO diff --git a/docs/data/batch/index.rst b/docs/data/batch/index.rst new file mode 100644 index 0000000..8e2e90e --- /dev/null +++ b/docs/data/batch/index.rst @@ -0,0 +1,13 @@ + +Data Batch Processing +===================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + schema + handlers + native + custom diff --git a/docs/data/batch/native.rst b/docs/data/batch/native.rst new file mode 100644 index 0000000..2d3839e --- /dev/null +++ b/docs/data/batch/native.rst @@ -0,0 +1,6 @@ + +================== +Native Batch Types +================== + +TODO diff --git a/docs/data/batch/overview.rst b/docs/data/batch/overview.rst new file mode 100644 index 0000000..402f72b --- /dev/null +++ b/docs/data/batch/overview.rst @@ -0,0 +1,6 @@ + +========== + Overview +========== + +TODO diff --git a/docs/data/batch/schema.rst b/docs/data/batch/schema.rst new file mode 100644 index 0000000..6ac5f36 --- /dev/null +++ b/docs/data/batch/schema.rst @@ -0,0 +1,6 @@ + +================== +Batch Table Schema +================== + +TODO diff --git a/docs/data/batches.rst b/docs/data/batches.rst deleted file mode 100644 index 39c38f1..0000000 --- a/docs/data/batches.rst +++ /dev/null @@ -1,5 +0,0 @@ - -Data Batch Processing -===================== - -TODO diff --git a/docs/data/datasync.rst b/docs/data/datasync.rst deleted file mode 100644 index 2017d51..0000000 --- a/docs/data/datasync.rst +++ /dev/null @@ -1,5 +0,0 @@ - -Data Synchronization -==================== - -TODO diff --git a/docs/data/index.rst b/docs/data/index.rst index adfa00e..fba96ad 100644 --- a/docs/data/index.rst +++ b/docs/data/index.rst @@ -10,9 +10,11 @@ Data Layer trainwreck other importing - datasync - batches + sync versioning + batch/index + reports/index + problems multinode tempmon tasks diff --git a/docs/data/problems.rst b/docs/data/problems.rst new file mode 100644 index 0000000..566931d --- /dev/null +++ b/docs/data/problems.rst @@ -0,0 +1,5 @@ + +Problem Reports +=============== + +TODO diff --git a/docs/data/reports/autoemail.rst b/docs/data/reports/autoemail.rst new file mode 100644 index 0000000..38882ae --- /dev/null +++ b/docs/data/reports/autoemail.rst @@ -0,0 +1,6 @@ + +==================== +Auto-Emailed Reports +==================== + +TODO diff --git a/docs/data/reports/custom.rst b/docs/data/reports/custom.rst new file mode 100644 index 0000000..bcc177c --- /dev/null +++ b/docs/data/reports/custom.rst @@ -0,0 +1,81 @@ + +======================== + Adding a Custom Report +======================== + +We'll start with a simple report which shows all departments and the number of +products for each. + +Each type of report has a "key" which uniquely identifies it. For this example +we'll use ``poser_dept_prod_counts`` for the key. Note that it's a good idea +to always use an app-specific prefix (e.g. ``poser_``) in the key. + +Typically you will create a new Python module which is named according to the +key. Here we'll create ``~/src/poser/poser/reports/dept_prod_counts.py``, and +in it we'll define the report:: + + from sqlalchemy import orm + + from rattail.reporting import ExcelReport + + + class DepartmentProductCounts(ExcelReport): + """ + Shows all departments and the number of products for each. + """ + type_key = 'poser_dept_prod_counts' + name = "Department Product Counts" + output_fields = [ + 'department_number', + 'department_name', + 'product_count', + ] + + def make_data(self, session, params, progress=None, **kwargs): + model = self.model + + # fetch all departments, with product lists pre-loaded + departments = session.query(model.Department)\ + .order_by(model.Department.number)\ + .options(orm.joinedload(model.Department.products))\ + .all() + rows = [] + + def add_row(department, i): + rows.append({ + 'department_number': department.number, + 'department_name': department.name, + 'product_count': len(department.products), + }) + + self.progress_loop(add_row, departments, progress, + message="Fetching data for report") + return rows + +Then you must register your new report type, to make it available to the app. +This is done within your project's ``setup.py`` file, for instance:: + + setup( + name = "Poser", + + # ... + + entry_points = { + + 'rattail.reports': [ + 'poser_dept_prod_counts = poser.reports.dept_prod_counts:DepartmentProductCounts', + ], + }, + ) + +Once you've added that you must re-install the app to your virtual environment, +for instance: + +.. code-block:: sh + + cd /srv/envs/poser + source bin/activate + pip install -e ~/src/poser + +At this point the report should be available for running within the app. See +:doc:`generate` for more info. diff --git a/docs/data/reports/generate.rst b/docs/data/reports/generate.rst new file mode 100644 index 0000000..3ed5a1a --- /dev/null +++ b/docs/data/reports/generate.rst @@ -0,0 +1,6 @@ + +=================== +Generating a Report +=================== + +TODO diff --git a/docs/data/reports/handler.rst b/docs/data/reports/handler.rst new file mode 100644 index 0000000..4832375 --- /dev/null +++ b/docs/data/reports/handler.rst @@ -0,0 +1,19 @@ + +============== +Report Handler +============== + +Each app will have exactly one "report handler" which is reponsible for the +overall logic of running and emailing reports etc. It also determines which +report types are available to be ran. + +Rattail provides a default report handler so unless you have custom +requirements, you will not need to define your own report handler. See the +:class:`~rattail:rattail.reporting.handlers.ReportHandler` class for more +details. + +Programmatically you can access your report handler like so:: + + # assuming you already have config + app = config.get_app() + handler = app.get_report_handler() diff --git a/docs/data/reports/index.rst b/docs/data/reports/index.rst new file mode 100644 index 0000000..bd5042a --- /dev/null +++ b/docs/data/reports/index.rst @@ -0,0 +1,13 @@ + +Reports +======= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + handler + generate + autoemail + custom diff --git a/docs/data/reports/overview.rst b/docs/data/reports/overview.rst new file mode 100644 index 0000000..d16d87f --- /dev/null +++ b/docs/data/reports/overview.rst @@ -0,0 +1,28 @@ + +========== + Overview +========== + +A report is conceptually just what you think it is, probably. But there are a +few related concepts which we'll try to briefly outline here. + +* report type +* report handler +* report output + +First a "report type" refers to the logic for running a specific type of +report. For example, "Daily Sales" or "Slow Movers" might be report types. +This defines what sort of data is included on the report, how it is displayed +etc. See :doc:`custom` for how to create a new report type. + +Next, a "report handler" is responsible for overall logic used to orchestrate +the running of all reports for the app. See :doc:`handler` for more on that. + +Finally "report output" refers to the result of running a report. Generally +speaking whenever a report runs, the details are saved to the DB for +convenience and historical record. See :doc:`generate` for more on that. + +It's perhaps worth noting, that in Rattail-speak "an email is not a report" and +vice versa. Meaning, a report is a *generated document* and if sent via email, +it will be an attachment as opposed to being part of the message body. See +also :doc:`autoemail`. diff --git a/docs/data/sync.rst b/docs/data/sync.rst new file mode 100644 index 0000000..c9d1264 --- /dev/null +++ b/docs/data/sync.rst @@ -0,0 +1,5 @@ + +Data Real-Time Sync +=================== + +TODO diff --git a/docs/index.rst b/docs/index.rst index 416f598..0307d14 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,10 +18,15 @@ Poser/Rattail app: * :doc:`base/index` - general app install, command line, plus filemon etc. * :doc:`data/index` - when a DB or data import/export come into it * :doc:`web/index` - all things web -* :doc:`luigi/index` - using Luigi for better overnight automation -* :doc:`deploy/index` - deals with production deployment +* :doc:`monitor/index` - keeping an eye out for production issues +* :doc:`deploy/index` - deploying a production system * :doc:`backup/index` - backing up the production system +.. note:: + Please understand, this manual is a work in progress. We finally have an + "authoritative home base" for this documentation, but it may take some time + to fill in all the blanks. + Please see `https://rattailproject.org/docs/rattail-manual/ `_ for the latest version of this document. @@ -35,7 +40,7 @@ this document. base/index data/index web/index - luigi/index + monitor/index deploy/index backup/index diff --git a/docs/luigi/index.rst b/docs/monitor/index.rst similarity index 60% rename from docs/luigi/index.rst rename to docs/monitor/index.rst index 7e102ff..cd8fdb3 100644 --- a/docs/luigi/index.rst +++ b/docs/monitor/index.rst @@ -1,6 +1,6 @@ -Luigi Layer -=========== +Monitoring Layer +================ .. toctree:: @@ -8,3 +8,4 @@ Luigi Layer :caption: Contents: overview + shinken diff --git a/docs/luigi/overview.rst b/docs/monitor/overview.rst similarity index 100% rename from docs/luigi/overview.rst rename to docs/monitor/overview.rst diff --git a/docs/monitor/shinken.rst b/docs/monitor/shinken.rst new file mode 100644 index 0000000..b656f78 --- /dev/null +++ b/docs/monitor/shinken.rst @@ -0,0 +1,5 @@ + +Shinken +======= + +TODO