Improve API documentation

docs/conf.py

@@ -11,6 +11,10 @@
 # sys.path.insert(0, os.path.abspath(".."))
 import servicex
 
+# the following is to propagate down to the pydantic class docstring builder
+import os
+
+os.environ["IN_SPHINX_BUILD"] = "1"
 
 project = "ServiceX"
 copyright = "2024 Institute for Research and Innovation in Software for High Energy Physics (IRIS-HEP)"  # NOQA 501
@@ -30,6 +34,7 @@
     "sphinxcontrib.autodoc_pydantic",
     "sphinx_tabs.tabs",
     "sphinx_copybutton",
+    "enum_tools.autoenum",
 ]
 
 templates_path = ["_templates"]

docs/modules.rst

@@ -1,7 +1,20 @@
 API documentation
 =================
 
+For the functions and classes you will enounter in general ``ServiceX`` use, see :doc:`servicex`.
+
+For documentation of the ``servicex.func_adl`` package, see :doc:`servicex.func_adl`.
+
+For documentation of the methods used by the command line application, see :doc:`servicex.app`.
+
+For documentation of other ``ServiceX`` internals, see :doc:`servicex_internals`.
+
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
+   :hidden:
 
    servicex
+   servicex_queries
+   servicex.func_adl
+   servicex.app
+   servicex_internals

docs/servicex.app.rst

@@ -1,4 +1,4 @@
-servicex.app package
+``servicex.app`` package
 ====================
 
 Submodules

docs/servicex.func_adl.rst

@@ -1,5 +1,5 @@
-servicex.func\_adl package
-==========================
+``servicex.func_adl`` package
+=============================
 
 Submodules
 ----------
@@ -12,22 +12,6 @@ servicex.func\_adl.func\_adl\_dataset module
    :undoc-members:
    :show-inheritance:
 
-servicex.func\_adl.func\_adl\_dataset\_group module
----------------------------------------------------
-
-.. automodule:: servicex.func_adl.func_adl_dataset_group
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.func\_adl.util module
-------------------------------
-
-.. automodule:: servicex.func_adl.util
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 Module contents
 ---------------
 

docs/servicex.rst

@@ -1,4 +1,4 @@
-servicex package
+``servicex`` package
 ================
 
 
@@ -9,120 +9,3 @@ Module contents
    :members:
    :undoc-members:
    :show-inheritance:
-
-
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 4
-
-   servicex.app
-   servicex.func_adl
-
-Submodules
-----------
-
-servicex.configuration module
------------------------------
-
-.. automodule:: servicex.configuration
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.databinder\_models module
-----------------------------------
-
-.. automodule:: servicex.databinder_models
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.dataset\_group module
-------------------------------
-
-.. automodule:: servicex.dataset_group
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.dataset\_identifier module
------------------------------------
-
-.. automodule:: servicex.dataset_identifier
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.expandable\_progress module
-------------------------------------
-
-.. automodule:: servicex.expandable_progress
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.minio\_adapter module
-------------------------------
-
-.. automodule:: servicex.minio_adapter
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.models module
-----------------------
-
-.. automodule:: servicex.models
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.python\_dataset module
--------------------------------
-
-.. automodule:: servicex.python_dataset
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.query module
----------------------
-
-.. automodule:: servicex.query
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.query\_cache module
-----------------------------
-
-.. automodule:: servicex.query_cache
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.servicex\_adapter module
----------------------------------
-
-.. automodule:: servicex.servicex_adapter
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.servicex\_client module
---------------------------------
-
-.. automodule:: servicex.servicex_client
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-servicex.types module
----------------------
-
-.. automodule:: servicex.types
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/servicex_internals.rst

@@ -0,0 +1,106 @@
+``servicex`` client internals
+==========
+
+servicex.configuration module
+-----------------------------
+
+.. automodule:: servicex.configuration
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.databinder\_models module
+----------------------------------
+
+.. automodule:: servicex.databinder_models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.dataset\_group module
+------------------------------
+
+.. automodule:: servicex.dataset_group
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.dataset\_identifier module
+-----------------------------------
+
+.. automodule:: servicex.dataset_identifier
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.expandable\_progress module
+------------------------------------
+
+.. automodule:: servicex.expandable_progress
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.minio\_adapter module
+------------------------------
+
+.. automodule:: servicex.minio_adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.models module
+----------------------
+
+.. automodule:: servicex.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.python\_dataset module
+-------------------------------
+
+.. automodule:: servicex.python_dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.query module
+---------------------
+
+.. automodule:: servicex.query
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.query\_cache module
+----------------------------
+
+.. automodule:: servicex.query_cache
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.servicex\_adapter module
+---------------------------------
+
+.. automodule:: servicex.servicex_adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.servicex\_client module
+--------------------------------
+
+.. automodule:: servicex.servicex_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+servicex.types module
+---------------------
+
+.. automodule:: servicex.types
+   :members:
+   :undoc-members:
+   :show-inheritance: