Automatically adding ARCHITECTURE.md to the documentation

apps/cli/executables/pexable/productfetcher/productfetcher/interfaces.py

@@ -74,7 +74,9 @@ class FileFetcher(ABC):
     implement a method to indicate whether they share resources,
     and if they do, FetchPlan groups them together to limit their
     concurrency. FetchPlan assumes that FileFetchers are disjoint
-    in their use of shared resources; i.e. that
+    in their use of shared resources; i.e. that if you have two
+    fetchers that do not share resources with each other, there
+    will never be a third fetcher that shares resources with both.
     """
 
     def __init__(self):
@@ -176,6 +178,13 @@ class FetcherFactory(ABC):
     def fetch_plan(
         self, fetchers: List[Union[FileFetcher, "FetchPlan"]], concurrency: int = 1
     ) -> "FetchPlan":
+        """
+        Run a number of other plans or fetches in a larger FetchPlan.
+
+        :param fetchers:  fetchers or plans
+        :param concurrency:  the number to run concurrently
+        :return: a new FetchPlan
+        """
         pass
 
 

docs/conf.py

@@ -35,7 +35,7 @@ author = "NRAO Science Support and Archive Team"
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary", "myst_parser"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -46,6 +46,12 @@ templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
+# -- Markdown suffix
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/index.rst

@@ -9,6 +9,7 @@ Welcome to the Workspaces documentation!
 .. toctree::
    :maxdepth: 1
 
+   source/architecture
    source/installation
    source/deployment
    source/api/index

docs/regenerate.sh

@@ -41,4 +41,31 @@ cat >> api/index.rst <<EOF
    If you have any feedback or requests for the documentation, let Nathan know.
 EOF
 
+
+# generate the architecture API index
+cat > architecture.rst <<'EOF'
+Architecture
+============
+
+The following pages are notes from the ARCHITECTURE.md files.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+EOF
+
+# go into the architecture folder
+rm -rf architecture
+mkdir architecture
+
+pushd architecture
+for file in $(find ../../.. -name ARCHITECTURE.md); do
+  mdfile=$(basename $(dirname $file)).md
+  ln -s $file $mdfile
+  echo "   architecture/$mdfile" >> ../architecture.rst
+done
+popd
+
 popd
\ No newline at end of file

docs/requirements.txt

@@ -11,6 +11,7 @@ kombu
 lxml
 marshmallow
 # mysqlclient
+myst-parser
 paramiko
 pandas
 pendulum

docs/source/api/datafetcher/modules.rst

+datafetcher
+===========
+
+.. toctree::
+   :maxdepth: 4
+

docs/source/api/index.rst

@@ -15,6 +15,7 @@ Hello!
    notification/modules
    capability/modules
    aat_wrest/modules
+   pexable/modules
    workspaces/modules
    ws_metrics/modules
    schema/modules
@@ -25,6 +26,7 @@ Hello!
    delivery/modules
    vela/modules
    tmpdir_eraser/modules
+   datafetcher/modules
    casa_envoy/modules
    messaging/modules
    channels/modules

docs/source/api/pexable/modules.rst

+pexable
+=======
+
+.. toctree::
+   :maxdepth: 4
+

docs/source/architecture.rst

+Architecture
+============
+
+The following pages are notes from the ARCHITECTURE.md files.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   architecture/workspaces.md
+   architecture/productfetcher.md
+   architecture/delivery.md

docs/source/architecture/delivery.md

+../../../apps/cli/executables/delivery/ARCHITECTURE.md
\ No newline at end of file

docs/source/architecture/productfetcher.md

+../../../apps/cli/executables/productfetcher/ARCHITECTURE.md
\ No newline at end of file

docs/source/architecture/workspaces.md

+../../../shared/workspaces/workspaces/ARCHITECTURE.md
\ No newline at end of file