diff --git a/docs/conf.py b/docs/conf.py index 4652d985..5553fddc 100644 --- a/docs/conf.py +++ b/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"] diff --git a/docs/modules.rst b/docs/modules.rst index b6b46282..5aa6fa37 100644 --- a/docs/modules.rst +++ b/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 diff --git a/docs/servicex.app.rst b/docs/servicex.app.rst index 88c2c33b..a04da8a4 100644 --- a/docs/servicex.app.rst +++ b/docs/servicex.app.rst @@ -1,4 +1,4 @@ -servicex.app package +``servicex.app`` package ==================== Submodules diff --git a/docs/servicex.databinder.rst b/docs/servicex.databinder.rst deleted file mode 100644 index 49589226..00000000 --- a/docs/servicex.databinder.rst +++ /dev/null @@ -1,22 +0,0 @@ -servicex.databinder_models -=========================== - -.. autopydantic_model:: servicex.databinder_models.ServiceXSpec - :members: - :model-show-field-summary: False - :undoc-members: - -.. autopydantic_model:: servicex.databinder_models.General - :exclude-members: to_ResultFormat - :members: - :model-show-validator-members: False - :model-show-validator-summary: False - :model-show-field-summary: False - :undoc-members: - -.. autopydantic_model:: servicex.databinder_models.Sample - :members: - :model-show-validator-members: False - :model-show-validator-summary: False - :model-show-field-summary: False - :undoc-members: diff --git a/docs/servicex.func_adl.rst b/docs/servicex.func_adl.rst index c35f4d72..3ac7a83d 100644 --- a/docs/servicex.func_adl.rst +++ b/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 --------------- diff --git a/docs/servicex.rst b/docs/servicex.rst index cad39046..6b339b59 100644 --- a/docs/servicex.rst +++ b/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: diff --git a/docs/servicex_client.rst b/docs/servicex_client.rst deleted file mode 100644 index f8d0d079..00000000 --- a/docs/servicex_client.rst +++ /dev/null @@ -1,7 +0,0 @@ -ServiceXClient -============== -.. autoclass:: servicex.servicex_client.ServiceXClient - :members: - :exclude-members: Config - :undoc-members: - :show-inheritance: diff --git a/docs/servicex_internals.rst b/docs/servicex_internals.rst new file mode 100644 index 00000000..498f4f2a --- /dev/null +++ b/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: diff --git a/docs/servicex_queries.rst b/docs/servicex_queries.rst new file mode 100644 index 00000000..84eb8d54 --- /dev/null +++ b/docs/servicex_queries.rst @@ -0,0 +1,57 @@ +Query classes +============= + +All the query classes are also made available under the package ``servicex.query`` and can be imported from there: + +.. list-table:: + :header-rows: 1 + + * - Name in ``servicex.query`` + - Original class name + * - ``PythonFunction`` + - :py:class:`servicex.python_dataset.PythonFunction` + * - ``UprootRaw`` + - :py:class:`servicex.uproot_raw.uproot_raw.UprootRawQuery` + * - ``FuncADL_Uproot`` + - :py:class:`servicex.func_adl.func_adl_dataset.FuncADLQuery_Uproot` + * - ``FuncADL_ATLASr21`` + - :py:class:`servicex.func_adl.func_adl_dataset.FuncADLQuery_ATLASr21` + * - ``FuncADL_ATLASr22`` + - :py:class:`servicex.func_adl.func_adl_dataset.FuncADLQuery_ATLASr22` + * - ``FuncADL_ATLASxAOD`` + - :py:class:`servicex.func_adl.func_adl_dataset.FuncADLQuery_ATLASxAOD` + * - ``FuncADL_CMS`` + - :py:class:`servicex.func_adl.func_adl_dataset.FuncADLQuery_CMS` + +So, for example, + +.. code:: python + + from servicex.query import FuncADL_Uproot + +is equivalent to + +.. code:: python + + from servicex.func_adl.func_adl_dataset import FuncADLQuery_Uproot + +Uproot-Raw queries +------------------ + +.. automodule:: servicex.uproot_raw.uproot_raw + :members: UprootRawQuery + +.. automodule:: servicex.uproot_raw.uproot_raw + :members: TreeSubQuery, CopyHistogramSubQuery + +Python queries +-------------- + +.. automodule:: servicex.python_dataset + :members: + +FuncADL queries +--------------- + +.. automodule:: servicex.func_adl.func_adl_dataset + :members: diff --git a/pyproject.toml b/pyproject.toml index 0764ae44..10ea332c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -90,6 +90,7 @@ docs = [ "autodoc-pydantic==2.2.0", "sphinx-tabs>=3.4.5", "sphinx-copybutton>=0.5.2", + "enum-tools[sphinx]>=0.12.0", ] develop = [ "servicex[test,docs]", diff --git a/servicex/models.py b/servicex/models.py index ed839f4a..871e7625 100644 --- a/servicex/models.py +++ b/servicex/models.py @@ -55,7 +55,12 @@ class DocStringBaseModel(BaseModel): @classmethod def __pydantic_init_subclass__(cls, **kwargs: Any): super().__pydantic_init_subclass__(**kwargs) - cls.__doc__ = _generate_model_docstring(cls) + # There is currently no good way of knowing we are building within Sphinx. + # Use a hacky workaround but monitor https://github.com/sphinx-doc/sphinx/issues/9805 + import os + + if "IN_SPHINX_BUILD" not in os.environ: + cls.__doc__ = _generate_model_docstring(cls) class ResultDestination(str, Enum):