Documentation: updates and fixes/review

docs/source/development.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Architecture\n",
     "\n",
-    "Each data schema supported by XRADIO is organized into its own sub-package, with a shared `_utils` directory that contains code common to multiple sub-packages as shown in [Figure 1](#figure-1). The current architecture includes the `measurement_set` and `image` sub-packages ([see the list of planned XRADIO schemas](https://xradio.readthedocs.io/en/latest/overview.html#XRADIO-Schemas)).\n",
+    "Each data schema supported by XRADIO is organized into its own sub-package, with a shared `_utils` directory that contains code common to multiple sub-packages as shown in [Figure 1](#figure-1). The current architecture includes the `measurement_set` and `image` sub-packages ([see the list of planned XRADIO schemas](overview.ipynb#XRADIO-Schemas)).\n",
     "\n",
     "The user-facing API is implemented in the `.py` files located at the top level of each sub-package directory, while private functions are housed in a dedicated sub-directory, such as `_measurement_set`. This sub-directory contains folders for each supported storage backend, as well as a `_utils` folder for common functions used across backends.\n",
     "\n",
@@ -17,7 +17,7 @@
     "<div style=\"text-align: center;\">\n",
     "    <figure id=\"figure-1\" style=\"display: inline-block;\">\n",
     "        <img src=\"https://docs.google.com/drawings/d/1afPe5oro26NMTkAKpK9iif0adNA0B4R9otLookOixvI/pub?w=943&amp;h=732\"\n",
-    "             alt=\"aaa.\"\n",
+    "             alt=\"diagram showing the XRADIO architecture: dependencies, modules, functions, etc.\"\n",
     "             style=\"display: block; margin: auto;\">\n",
     "        <figcaption>Figure 1: XRADIO Architecture.</figcaption>\n",
     "    </figure>\n",
@@ -45,24 +45,26 @@
    "source": [
     "# Schema Design\n",
     "\n",
-    "For this section to make sense please ensure to have completed the [foundational reading](https://xradio.readthedocs.io/en/latest/overview.html#Foundational-Reading) on Xarray terminology.\n",
+    "For this section to make sense please ensure to have completed the [foundational reading](overview.ipynb#Foundational-Reading) on Xarray terminology.\n",
     "\n",
     "For each of the schemas data is organized into:\n",
+    "\n",
     "- [xarray Datasets](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html): A multi-dimensional, array database of labeled n-dimensional arrays.\n",
-    "- `XRADIO Processing Sets`: XRADIO-specific data structure, based on a Python dictionary, that consists of a collection of `xarray Datasets`. We will be looking into replacing the Processing set with [`xarray Datatree`](https://xarray-datatree.readthedocs.io/en/latest/) in the future.\n",
+    "- `XRADIO Processing Sets`: XRADIO-specific data structure, based on a Python dictionary, that consists of a collection of `xarray Datasets`. We will be looking into replacing the Processing set with [xarray Datatree](https://xarray-datatree.readthedocs.io/en/latest/) in the future.\n",
     "\n",
     "\n",
     "## Coordinates and Data Variables\n",
     "\n",
     "In XRADIO, we follow these conventions when defining a data schema:\n",
+    "\n",
     "- **Coordinates**: Values used to label plots (e.g., numbers or strings). Coordinate names are always in lower case and use snake_case.\n",
     "- **Data Variables**: Numerical values used for plotting. Data variable names are always in upper case and use snake_case.\n",
     "\n",
-    "For instance, in the [Measurement Set v4 schema](https://xradio.readthedocs.io/en/latest/measurement_set/schema_and_api/measurement_set_schema.html), `antenna_name` and `frequency` are coordinates, while `VISIBILITY` data are data variables.\n",
+    "For instance, in the [Measurement Set v4 schema](measurement_set/schema_and_api/measurement_set_schema.rst), `antenna_name` and `frequency` are coordinates, while `VISIBILITY` data are data variables.\n",
     "\n",
     "## Measures\n",
     "\n",
-    "Both data variables and coordinates can have additional metadata, such as associated coordinates and units, stored in their attributes. XRADIO’s measures are based on [`python-casacore` measures](https://casacore.github.io/python-casacore/casacore_measures.html), with updates to align with [astropy coordinate](https://docs.astropy.org/en/stable/coordinates/index.html) naming conventions. The table below outlines the different types of XRADIO measures:\n",
+    "Both data variables and coordinates can have additional metadata, such as associated coordinates and units, stored in their attributes. XRADIO’s measures are based on [python-casacore measures](https://casacore.github.io/python-casacore/casacore_measures.html), with updates to align with [astropy coordinate](https://docs.astropy.org/en/stable/coordinates/index.html) naming conventions. The table below outlines the different types of XRADIO measures:\n",
     "\n",
     ".. autoclass:: xradio.measurement_set.schema.TimeArray()\n",
     "\n",