Problematy · raven-wing · Aug 18, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/Makefile b/Makefile
@@ -37,13 +37,6 @@ dependency-check:
 run-example-env:
 	$(PYTHON) flask --app "goodmap.goodmap:create_app(config_path='$(CONFIG_PATH)')" --debug run
 
-verify-json-data:
-ifndef JSON_DATA_FILE
-	$(error "Missing required argument JSON_DATA_FILE: make verify-json-data JSON_DATA_FILE=path/to/json")
-else
-	$(PYTHON) python -m goodmap.data_validator $(JSON_DATA_FILE)
-endif
-
 extract-translations:
 	$(PYTHON) pybabel extract ./goodmap -o extracted.pot -F ./babel.cfg --project=goodmap
 	$(PYTHON) pybabel update -i extracted.pot -d goodmap/locale --ignore-pot-creation-date --ignore-obsolete

diff --git a/README.md b/README.md
@@ -18,16 +18,8 @@ Each has its own dependency manager (`poetry` for the backend and e2e-tests, `np
 
 #### 0. Clone the repo
 ```
-git clone --recursive
+git clone https://github.com/Problematy/goodmap.git
 ```
-Remember, everytime you want to pull the newest changes, run:
-```
-git pull
-git submodule update
-```
-because `goodmap` contains a submodule.
-
-#TODO remove all submodule connected instructions after removing platzky submodule (see #157)
 
 #### 1. Use python 3.10
 If you have a different version of Python on your system, install python 3.10 alongside. For that, you can use [`pyenv`](https://github.com/pyenv/pyenv). Follow the [documentation](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation). Useful commands: `pyenv help <command>`, `pyenv install`, `pyenv shell`, `pyenv versions`.

diff --git a/config-template.yml b/config-template.yml
@@ -30,13 +30,3 @@ DB:
 #   TYPE: google_hosted_json_file
 #   BUCKET_NAME: good-map
 #   SOURCE_BLOB_NAME: data.json
-
-
-PLUGINS:
-  sendmail:
-    PORT: 465
-    SERVER: "smtp.example.com"
-    RECEIVER: "receiver@example.com"
-    USER: "sender@example.pl"
-    PASSWORD: "PA$$WORD"
-    SUBJECT: "My awesome goodmap application"
diff --git a/docs/api-reference.rst b/docs/api-reference.rst
@@ -0,0 +1,121 @@
+Python API reference
+====================
+
+Generated from the source. This is the reference for code you *import* — writing a
+plugin, embedding the app, or working on Goodmap itself. If you are calling Goodmap over
+HTTP instead, you want :doc:`http-api`; if you are configuring an instance, you want
+:doc:`configuration`.
+
+Nothing here is a substitute for the task pages: use those to find out *which* thing to
+reach for, and this page for its exact signature.
+
+.. note::
+
+   Only the ``goodmap`` package is covered. Everything a Goodmap deployment inherits from
+   platzky — the engine, blog, plugin loader — is documented in
+   :doc:`platzky's own reference <platzky:index>`.
+
+Creating the application
+------------------------
+
+The documented way to build an app is the factory, given a path to ``config.yml``. It is
+what ``flask --app`` and ``gunicorn`` take as their target string (:doc:`deployment`).
+
+.. autofunction:: goodmap.goodmap.create_app
+
+.. autoclass:: goodmap.config.GoodmapConfig
+   :members:
+   :show-inheritance:
+
+``GoodmapConfig`` is a platzky ``Config`` with Goodmap's extra keys, and it is what
+``create_app`` parses the YAML into. The prose description of every key is in
+:doc:`configuration`.
+
+Plugins
+-------
+
+The capability base classes a plugin subclasses. Which capability does what, and how a
+plugin is packaged and activated, is covered in :doc:`plugins`.
+
+.. automodule:: goodmap.plugin
+   :members:
+   :show-inheritance:
+
+Location data
+-------------
+
+The models every point is validated against — both points already in the data source and
+points arriving through ``/api/suggest-new-point``. ``create_location_model`` is the one
+to know: it builds a model from your data source's ``location_obligatory_fields`` and
+``categories`` at startup, which is why those keys are validation rules and not just
+documentation (:doc:`data-source`).
+
+.. automodule:: goodmap.data_models.location
+   :members:
+   :show-inheritance:
+
+Request and response models
+---------------------------
+
+Pydantic models for the HTTP layer. These are what generate the OpenAPI document served
+at ``/api/doc/openapi.json``, so they and the schema endpoint never disagree.
+
+.. automodule:: goodmap.api_models
+   :members:
+   :show-inheritance:
+
+Data access
+-----------
+
+The data-source layer: one implementation per ``DB.TYPE``, plus the query functions the
+API blueprint calls. Backend trade-offs and the MongoDB layout are in
+:ref:`data-source-backends`.
+
+.. automodule:: goodmap.db
+   :members:
+   :show-inheritance:
+
+Querying, filtering and clustering
+----------------------------------
+
+How a request's query parameters become a list of points: filter combination, distance
+sorting and limiting, then optional server-side clustering.
+
+.. automodule:: goodmap.core
+   :members:
+
+.. automodule:: goodmap.filtering
+   :members:
+
+.. automodule:: goodmap.clustering
+   :members:
+
+Formatting
+----------
+
+Translation of category keys, option values and field names on the way out
+(:ref:`config-translations`).
+
+.. automodule:: goodmap.formatter
+   :members:
+
+Errors
+------
+
+Exceptions raised by the data layer, and the helpers that turn them into the deliberately
+generic ``{"message": "..."}`` responses described in :doc:`http-api`.
+
+.. automodule:: goodmap.exceptions
+   :members:
+   :show-inheritance:
+
+Input hardening
+---------------
+
+Limits applied to JSON arriving from the network before it is parsed into a point. The
+concrete numbers, and the response you get for exceeding them, are in
+:doc:`http-api`.
+
+.. automodule:: goodmap.json_security
+   :members:
+   :show-inheritance:
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -4,7 +4,6 @@
 import sys
 from pathlib import Path
 
-# Add project to path
 project_root = Path(__file__).parent.parent
 sys.path.insert(0, str(project_root))
 
@@ -24,8 +23,8 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
     "myst_parser",
 ]
 
@@ -53,24 +52,31 @@
     ]
 }
 
-# Autodoc settings
 autodoc_member_order = "bysource"
 autodoc_typehints = "description"
 
-# Intersphinx mapping
+# Napoleon settings: docstrings in this project are Google style.
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+
+_ANY_PY_ROLE = "py:.*"
+nitpick_ignore_regex = [
+    (_ANY_PY_ROLE, r"ConfigDict|callable"),
+    (_ANY_PY_ROLE, r"(annotated_types|pymongo)\..*"),
+    (_ANY_PY_ROLE, r"[gl]e=-?\d+"),
+    (
+        _ANY_PY_ROLE,
+        r"platzky\.(Engine|feature_flags_wrapper\.FeatureFlagSet|plugin\.plugin\.PluginBase)",
+    ),
+]
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "flask": ("https://flask.palletsprojects.com/en/stable/", None),
     "pydantic": ("https://docs.pydantic.dev/latest/", None),
     "platzky": ("https://platzky.readthedocs.io/en/latest/", None),
 }
 
-# Napoleon settings for Google/NumPy style docstrings
-napoleon_google_docstring = True
-napoleon_numpy_docstring = False
-napoleon_include_init_with_doc = True
-
-# Make version available as substitution in RST files
 rst_epilog = f"""
 .. |version| replace:: {version}
 """