ArgLab · bradley-erickson · Sep 19, 2025 · Sep 18, 2025
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.1.0+2025.08.15T13.29.30.819Z.f61cb8b1.master
+0.1.0+2025.09.18T20.00.55.977Z.4d8e2b48.berickson.2025.document.restructure
diff --git a/autodocs/.gitignore b/autodocs/.gitignore
@@ -1,3 +1,4 @@
 _build/
 generated/
 apidocs/
+module_readmes/
diff --git a/autodocs/api.rst b/autodocs/api.rst
@@ -2,5 +2,6 @@ API
 ===
 
 .. toctree::
+   :maxdepth: 4
 
    apidocs/index
diff --git a/autodocs/concepts.rst b/autodocs/concepts.rst
@@ -0,0 +1,18 @@
+Concepts
+=============
+
+Explanations of key ideas, principles, and background knowledge.
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   docs/concepts/architecture.md
+   docs/concepts/auth.md
+   docs/concepts/events.md
+   docs/concepts/history.md
+   docs/concepts/privacy.md
+   docs/concepts/reducers.md
+   docs/concepts/scaling.md
+   docs/concepts/system_design.md
+   docs/concepts/technologies.md
diff --git a/autodocs/conf.py b/autodocs/conf.py
@@ -1,5 +1,8 @@
-import sys
 import os
+import pathlib
+import shutil
+import sphinx.util
+import sys
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -9,7 +12,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'Learning Observer'
-copyright = '2023, Bradley Erickson'
+copyright = '2020-2025, Bradley Erickson'
 author = 'Bradley Erickson'
 
 # -- General configuration ---------------------------------------------------
@@ -26,6 +29,9 @@
     '../modules/writing_observer/writing_observer'
 ]
 
+autodoc2_output_dir = 'apidocs'
+autodoc2_member_order = 'bysource'
+
 source_suffix = {
     '.rst': 'restructuredtext',
     '.md': 'markdown',
@@ -40,3 +46,31 @@
 
 html_theme = 'alabaster'
 html_static_path = ['_static']
+
+LOGGER = sphinx.util.logging.getLogger(__name__)
+
+
+def _copy_module_readmes(app):
+    """Populate ``module_readmes`` with module README files."""
+
+    docs_root = pathlib.Path(__file__).parent.resolve()
+    modules_root = docs_root.parent / 'modules'
+    destination_root = docs_root / 'module_readmes'
+
+    if not modules_root.exists():
+        LOGGER.warning("modules directory %s was not found", modules_root)
+        return
+
+    if destination_root.exists():
+        shutil.rmtree(destination_root)
+    destination_root.mkdir(parents=True, exist_ok=True)
+
+    readme_paths = sorted(modules_root.glob('*/README.md'))
+    for readme_path in readme_paths:
+        module_name = readme_path.parent.name
+        destination_path = destination_root / f"{module_name}.md"
+        shutil.copy2(readme_path, destination_path)
+
+
+def setup(app):
+    app.connect('builder-inited', _copy_module_readmes)
diff --git a/autodocs/development.rst b/autodocs/development.rst
diff --git a/autodocs/docs b/autodocs/docs
@@ -0,0 +1 @@
+../docs/
diff --git a/autodocs/how-to.rst b/autodocs/how-to.rst
@@ -0,0 +1,14 @@
+How-to
+=============
+
+Practical instructions to solve specific problems or achieve goals.
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   docs/how-to/config.md
+   docs/how-to/dashboards.md
+   docs/how-to/docker.md
+   docs/how-to/extension.md
+   docs/how-to/interactive_environments.md
diff --git a/autodocs/images.rst b/autodocs/images.rst
diff --git a/autodocs/index.rst b/autodocs/index.rst
@@ -12,14 +12,21 @@ per-student writing data, and aggegators to make dashboards. We've
 tested this in math and writing, but our focus is on writing process
 data.
 
+Our documentation is organized into four main categories, each serving a different purpose. You can explore them below:
+
+- :doc:`Tutorials <tutorials>` - Step-by-step guides to help you learn by doing.
+- :doc:`Concepts <concepts>` - Explanations of key ideas and background knowledge.
+- :doc:`How-To <how-to>` - Practical instructions to solve specific goals.
+- :doc:`Reference <reference>` - Detailed API/configuration information.
+
 .. toctree::
-   :maxdepth: 2
+   :hidden:
+   :maxdepth: 3
 
-   development
-   system_design
-   modules
-   extension
-   api
+   tutorials
+   concepts
+   how-to
+   reference
 
 Additional Information
 ----------------------

diff --git a/autodocs/modules.rst b/autodocs/modules.rst
@@ -1,11 +1,9 @@
-.. _modules:
-
 Modules
 -----------
+The module READMEs are collected automatically during the Sphinx build.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
 
-.. include:: ../modules/lo_dash_react_components/README.md
-   :parser: myst_parser.sphinx_
-.. include:: ../modules/lo_event/README.md
-   :parser: myst_parser.sphinx_
-.. include:: ../modules/writing_observer/README.md
-   :parser: myst_parser.sphinx_
+   module_readmes/*
diff --git a/autodocs/reference.rst b/autodocs/reference.rst
@@ -0,0 +1,16 @@
+Reference
+=============
+
+Detailed, structured information about APIs, configurations, and technical details.
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   docs/reference/code_quality.md
+   docs/reference/documentation.md
+   docs/reference/linting.md
+   docs/reference/testing.md
+   docs/reference/versioning.md
+   modules
+   api
diff --git a/autodocs/system_design.rst b/autodocs/system_design.rst
diff --git a/autodocs/tutorials.rst b/autodocs/tutorials.rst
@@ -0,0 +1,11 @@
+Tutorials
+=============
+
+Step-by-step guides to help you learn by doing.
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   docs/tutorials/workshop.md
+   docs/tutorials/install.md
diff --git a/docs/architecture.md → docs/concepts/architecture.md b/docs/architecture.md → docs/concepts/architecture.md
diff --git a/docs/auth.md → docs/concepts/auth.md b/docs/auth.md → docs/concepts/auth.md
diff --git a/docs/events.md → docs/concepts/events.md b/docs/events.md → docs/concepts/events.md
diff --git a/docs/history.md → docs/concepts/history.md b/docs/history.md → docs/concepts/history.md
diff --git a/docs/privacy.md → docs/concepts/privacy.md b/docs/privacy.md → docs/concepts/privacy.md
diff --git a/docs/reducers.md → docs/concepts/reducers.md b/docs/reducers.md → docs/concepts/reducers.md
diff --git a/docs/scaling.md → docs/concepts/scaling.md b/docs/scaling.md → docs/concepts/scaling.md
diff --git a/docs/system_design.md → docs/concepts/system_design.md b/docs/system_design.md → docs/concepts/system_design.md
@@ -20,7 +20,7 @@ Our goal is to build a system which will:
 
 In other words:
 
-![](_images/block.png)
+![](../_images/block.png)
 
 Internally, the system takes a stream of events from each learner, and
 routes it to one or more analytics modules. Each of these modules
@@ -37,7 +37,7 @@ through instructors for such an aggregation, and only aggregate where
 data has changed, so that with large numbers of instructors, the
 system merely updates dashboards less quickly:
 
-![](_images/lo_block.png)
+![](../_images/lo_block.png)
 
 Although at present, reduce operations are per-student, and
 aggregations per-class, in the future, we envision:
@@ -51,6 +51,6 @@ aggregations per-class, in the future, we envision:
 
 Data will be stored in a git-like Merkle tree format: 
 
-![](_images/mmnd.png)
+![](../_images/mmnd.png)
 
 We'll document this in more detail later.
diff --git a/docs/technologies.md → docs/concepts/technologies.md b/docs/technologies.md → docs/concepts/technologies.md
diff --git a/docs/config.md → docs/how-to/config.md b/docs/config.md → docs/how-to/config.md
diff --git a/docs/dashboards.md → docs/how-to/dashboards.md b/docs/dashboards.md → docs/how-to/dashboards.md
diff --git a/docs/docker.md → docs/how-to/docker.md b/docs/docker.md → docs/how-to/docker.md
diff --git a/docs/extension.md → docs/how-to/extension.md b/docs/extension.md → docs/how-to/extension.md
diff --git a/docs/interactive_environments.md → docs/how-to/interactive_environments.md b/docs/interactive_environments.md → docs/how-to/interactive_environments.md
diff --git a/docs/code_quality.md → docs/reference/code_quality.md b/docs/code_quality.md → docs/reference/code_quality.md
diff --git a/docs/documentation.md → docs/reference/documentation.md b/docs/documentation.md → docs/reference/documentation.md
diff --git a/docs/linting.md → docs/reference/linting.md b/docs/linting.md → docs/reference/linting.md
diff --git a/docs/testing.md → docs/reference/testing.md b/docs/testing.md → docs/reference/testing.md
diff --git a/docs/versioning.md → docs/reference/versioning.md b/docs/versioning.md → docs/reference/versioning.md
diff --git a/docs/install.md → docs/tutorials/install.md b/docs/install.md → docs/tutorials/install.md
diff --git a/docs/workshop.md → docs/tutorials/workshop.md b/docs/workshop.md → docs/tutorials/workshop.md
diff --git a/docs/workshop_creds.md → docs/tutorials/workshop_creds.md b/docs/workshop_creds.md → docs/tutorials/workshop_creds.md
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		0.1.0+2025.08.15T13.29.30.819Z.f61cb8b1.master
		0.1.0+2025.09.18T20.00.55.977Z.4d8e2b48.berickson.2025.document.restructure