From f2809ff885a631fd47ac558e87ed8ad1cbefe2f0 Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@edbob.org>
Date: Thu, 13 Jan 2022 21:44:36 -0600
Subject: [PATCH] Add basic docs for adding new vendor catalog parser

---
 docs/data/batch/native/index.rst          |  2 +-
 docs/data/batch/native/vendor_catalog.rst | 52 +++++++++++++++++++++++
 2 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/docs/data/batch/native/index.rst b/docs/data/batch/native/index.rst
index 4eb2e8a..0d855b0 100644
--- a/docs/data/batch/native/index.rst
+++ b/docs/data/batch/native/index.rst
@@ -9,7 +9,7 @@ Of course you can always make your own batch types for other purposes;
 see :doc:`/data/batch/custom`.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    custorder
diff --git a/docs/data/batch/native/vendor_catalog.rst b/docs/data/batch/native/vendor_catalog.rst
index 77c1425..1fe479b 100644
--- a/docs/data/batch/native/vendor_catalog.rst
+++ b/docs/data/batch/native/vendor_catalog.rst
@@ -16,3 +16,55 @@ file parsers needed.)
 
 In any case executing this batch will just update Rattail by default;
 you may want a custom handler to update your POS system instead.
+
+
+Adding a New Vendor Catalog File Parser
+---------------------------------------
+
+Let's say you buy product from a vendor named "Acme Distribution" and
+you want to add support for their catalog file format.
+
+First you must define the file parser class, and register it.
+
+We suggest keeping catalog parsers in a particular folder, e.g.
+``~/src/poser/poser/vendor/catalogs/`` in your project.  Create
+folders as needed and then within that create a new file ``acme.py``
+and for now just put this in it::
+
+   from rattail.vendors.catalogs import CatalogParser
+
+   class AcmeCatalogParser(CatalogParser):
+
+       key = 'poser.acme'
+       vendor_key = 'poser.acme'
+
+Now you must register it.  To do this, first add something like the
+following to ``setup.py`` for your project::
+
+   setup(
+       # ...
+
+       entry_points = {
+           'rattail.vendors.catalogs.parsers': [
+               'poser.acme = poser.vendors.catalogs.acme:AcmeCatalogParser',
+           ],
+       },
+   )
+
+Then re-install your project, e.g. with:
+
+.. code-block:: sh
+
+   cd /srv/envs/poser
+   bin/pip install -e ~/src/poser
+
+At this point your parser should be visible within the web app and you
+can move on to fleshing out the parser logic, and test it by making a
+new batch in the web app etc.
+
+See :class:`rattail:rattail.vendors.catalogs.CatalogParser` for
+details of what attributes and methods you can implement.
+
+See
+https://kallithea.rattailproject.org/rattail-project/rattail/files/master/rattail/contrib/vendors/catalogs/
+for some example parsers.