modular parser framework

docs/conf.py

@@ -20,7 +20,7 @@ sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
-project = u'OpenMensa Potsdam'
+project = u'OpenMensa Parsers'
 copyright = u'2019, f4lco'
 author = u'f4lco'
 
@@ -123,7 +123,7 @@ html_sidebars = {
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'OpenMensaPotsdamdoc'
+htmlhelp_basename = 'OpenMensaParsersdoc'
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -150,7 +150,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'OpenMensaPotsdam.tex', u'OpenMensa Potsdam Documentation',
+    (master_doc, 'OpenMensaParsers.tex', u'OpenMensa Parsers Documentation',
      u'f4lco', 'manual'),
 ]
 
@@ -160,7 +160,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'openmensapotsdam', u'OpenMensa Potsdam Documentation',
+    (master_doc, 'openmensaparsers', u'OpenMensa Parsers Documentation',
      [author], 1)
 ]
 
@@ -171,8 +171,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'OpenMensaPotsdam', u'OpenMensa Potsdam Documentation',
-     author, 'OpenMensaPotsdam', 'One line description of project.',
+    (master_doc, 'OpenMensaParsers', u'OpenMensa Parsers Documentation',
+     author, 'OpenMensaParsers', 'One line description of project.',
      'Miscellaneous'),
 ]
 

docs/dev.rst

@@ -25,19 +25,53 @@ Main Module Entry Points
 In the following the main workflow of this parser is explained.
 Generating a new `OpenMensa` feed starts by reading the configured canteens. Some canteen data, such as ID, name, and location, are currently not scraped. Doing so would be very brittle and involve a multistep process. Refer to the :ref:`cache_hash` for deeper insight into the obstacles.
 
-.. autofunction:: stw_potsdam.config.read_canteen_config
+.. autofunction:: openmensa_parsers.config.read_canteen_config
 
-.. autoclass:: stw_potsdam.config.Canteen
+.. autoclass:: openmensa_parsers.config.Canteen
 
 Use the canteen data to select matching upstream outlets, download the required menu JSON, and render the OpenMensa XML.
 
-.. autoclass:: stw_potsdam.swp_webspeiseplan_api.SWPWebspeiseplanAPI
+Parser Providers
+~~~~~~~~~~~~~~~~
 
-.. autoclass:: stw_potsdam.swp_webspeiseplan_parser.SWPWebspeiseplanParser
+The application is structured around parser providers. A provider owns the
+source-specific work: fetching raw upstream data and converting it into the
+shared OpenMensa XML structures. The ``Builder`` only asks a provider for
+canteens, attaches feed metadata, and renders XML.
+
+New cities or data sources should add a parser under ``openmensa_parsers.parsers``.
+The parser should implement three methods:
+
+``fetch()``
+    Download or load the raw source data.
+
+``parse(config, raw_data)``
+    Convert raw data into a ``dict[str, CanteenXML]`` keyed by the configured
+    canteen key.
+
+``create_feed(canteen, url)``
+    Return the feed metadata for one canteen. In most cases, subclass
+    ``BaseOpenMensaParser`` and configure ``feed`` instead of overriding this
+    method.
+
+Register the parser in ``openmensa_parsers.parsers.registry``. At runtime, select a
+parser with ``OM_PARSER_ID``. The default is ``potsdam``.
+
+Parser tests should keep network access separate from parsing. Store raw
+fixtures in the test suite, pass them directly into ``parse()``, and reserve
+live source checks for opt-in tests.
+
+.. autoclass:: openmensa_parsers.webspeiseplan_api.WebspeiseplanAPI
+
+.. autoclass:: openmensa_parsers.webspeiseplan_parser.WebspeiseplanParser
+
+.. autoclass:: openmensa_parsers.parsers.base.BaseOpenMensaParser
+
+.. autoclass:: openmensa_parsers.parsers.potsdam.PotsdamParser
 
 The XML type modules contain the OpenMensa rendering objects:
 
-.. autoclass:: stw_potsdam.xml_types.builder.Builder
+.. autoclass:: openmensa_parsers.xml_types.builder.Builder
 
 Tests
 ~~~~~
@@ -55,5 +89,3 @@ Test execution works as follows: ::
 
 The first invocation runs tests whose outcome can solely be determined by the test suite, which makes them suitable for frequent execution and CI systems.
 Setting the environment variable ``ENABLE_API_QUERY`` enables tests which require querying the canteen API. Because third-party services are queried, those are more suited to manual execution. Developers can quickly check if their change is applicable to today's menu.
-
-

docs/index.rst

@@ -1,4 +1,4 @@
-Welcome to OpenMensa Parser Potsdam's documentation!
+Welcome to OpenMensa Parsers' documentation!
 ====================================================
 
 An OpenMensa parser retrieves canteen menus and renders them in a commonly understood format.