From 9a18d6cdded68758a0a72bd27c444de87e3a28b1 Mon Sep 17 00:00:00 2001 From: Priyansh Agrawal Date: Tue, 15 Oct 2024 13:41:47 +0100 Subject: [PATCH] Move docs to docstrings and generate documentation with sphinx-autodoc (#367) --- doc/source/api.rst | 54 ++----------------------------------------- doc/source/conf.py | 14 +++++++++++ environment.yml | 2 +- src/pantab/_reader.py | 26 ++++++++++++++++++--- src/pantab/_writer.py | 25 ++++++++++++++++++-- 5 files changed, 63 insertions(+), 58 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 48e4375d..694cade1 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -1,55 +1,5 @@ API Reference ============= -.. py:function:: frame_to_hyper(df: pd.DataFrame, database: Union[str, pathlib.Path], *, table: Union[str, tableauhyperapi.Name, tableauhyperapi.TableName], table_mode: str = "w", not_null_columns: Optional[Iterable[str]] = None, json_columns: Optional[Iterable[str]] = None, geo_columns: Optional[Iterable[str]] = None) -> None: - - Convert a DataFrame to a .hyper extract. - - :param df: Data to be written out. - :param database: Name / location of the Hyper file to write to. - :param table: Table to write to. - :param table_mode: The mode to open the table with. Default is "w" for write, which truncates the file before writing. Another option is "a", which will append data to the file if it already contains information. - :param not_null_columns: Columns which should be considered "NOT NULL" in the target Hyper database. By default, all columns are considered nullable - :param json_columns: Columns to be written as a JSON data type - :param geo_columns: Columns to be written as a GEOGRAPHY data type - :param process_params: Parameters to pass to the Hyper Process constructor. - -.. py:function:: frame_from_hyper(source: Union[str, pathlib.Path, tab_api.Connection], *, table: Union[str, tableauhyperapi.Name, tableauhyperapi.TableName], return_type: Literal["pandas", "pyarrow", "polars"] = "pandas") - - Extracts a DataFrame from a .hyper extract. - - :param source: Name / location of the Hyper file to be read or Hyper-API connection. - :param table: Table to read. - :param return_type: The type of DataFrame to be returned - :param process_params: Parameters to pass to the Hyper Process constructor. - - -.. py:function:: frames_to_hyper(dict_of_frames: Dict[Union[str, tableauhyperapi.Name, tableauhyperapi.TableName], pd.DataFrame], database: Union[str, pathlib.Path], *, table_mode: str = "w", not_null_columns: Optional[Iterable[str]] = None, json_columns: Optional[Iterable[str]] = None, geo_columns: Optional[Iterable[str]] = None,) -> None: - - Writes multiple DataFrames to a .hyper extract. - - :param dict_of_frames: A dictionary whose keys are valid table identifiers and values are dataframes - :param database: Name / location of the Hyper file to write to. - :param table_mode: The mode to open the table with. Default is "w" for write, which truncates the file before writing. Another option is "a", which will append data to the file if it already contains information. - :param not_null_columns: Columns which should be considered "NOT NULL" in the target Hyper database. By default, all columns are considered nullable - :param json_columns: Columns to be written as a JSON data type - :param geo_columns: Columns to be written as a GEOGRAPHY data type - :param process_params: Parameters to pass to the Hyper Process constructor. - -.. py:function:: frames_from_hyper(source: Union[str, pathlib.Path, tab_api.Connection], *, return_type: Literal["pandas", "pyarrow", "polars"] = "pandas") -> dict: - - Extracts tables from a .hyper extract. - - :param source: Name / location of the Hyper file to be read or Hyper-API connection. - :param return_type: The type of DataFrame to be returned - :param process_params: Parameters to pass to the Hyper Process constructor. - - -.. py:function:: frame_from_hyper_query(source: Union[str, pathlib.Path, tab_api.Connection], query: str, *, return_type: Literal["pandas", "polars", "pyarrow"] = "pandas",) - - Executes a SQL query and returns the result as a pandas dataframe - - :param source: Name / location of the Hyper file to be read or Hyper-API connection. - :param query: SQL query to execute. - :param return_type: The type of DataFrame to be returned - :param process_params: Parameters to pass to the Hyper Process constructor. +.. automodule:: pantab + :members: diff --git a/doc/source/conf.py b/doc/source/conf.py index 59de5060..c9e20188 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,5 +1,10 @@ +import pathlib +import sys from typing import List +srcdir = pathlib.Path(__file__).resolve().parent.parent.parent / "src" +sys.path.insert(0, str(srcdir)) + # -- Project information ----------------------------------------------------- project = "pantab" @@ -13,6 +18,8 @@ extensions = [ "sphinx_rtd_theme", "sphinxext.opengraph", + "sphinx.ext.autodoc", + "sphinx_autodoc_typehints", ] templates_path = ["_templates"] @@ -35,3 +42,10 @@ ogp_site_url = "https://pantab.readthedocs.io/" ogp_use_first_image = False ogp_image = "https://pantab.readthedocs.io/en/latest/_static/pantab_logo.png" + +# -- Options for autodoc ----------------------------------------------------- + +autodoc_mock_imports = ["pantab.libpantab"] +autodoc_typehints = "none" +typehints_use_signature = True +typehints_use_signature_return = True diff --git a/environment.yml b/environment.yml index 2b32f211..f7214664 100644 --- a/environment.yml +++ b/environment.yml @@ -15,9 +15,9 @@ dependencies: - pyarrow - python - pytest - - pytest_xdist - scikit-build-core - sphinx + - sphinx-autodoc-typehints - pre-commit - sphinx_rtd_theme - sphinxext-opengraph diff --git a/src/pantab/_reader.py b/src/pantab/_reader.py index 56b0aa65..2fbfa4f9 100644 --- a/src/pantab/_reader.py +++ b/src/pantab/_reader.py @@ -14,7 +14,14 @@ def frame_from_hyper_query( return_type: Literal["pandas", "polars", "pyarrow"] = "pandas", process_params: Optional[dict[str, str]] = None, ): - """See api.rst for documentation.""" + """ + Executes a SQL query and returns the result as a pandas dataframe + + :param source: Name / location of the Hyper file to be read or Hyper-API connection. + :param query: SQL query to execute. + :param return_type: The type of DataFrame to be returned + :param process_params: Parameters to pass to the Hyper Process constructor. + """ if process_params is None: process_params = {} @@ -44,7 +51,14 @@ def frame_from_hyper( return_type: Literal["pandas", "polars", "pyarrow"] = "pandas", process_params: Optional[dict[str, str]] = None, ): - """See api.rst for documentation""" + """ + Extracts a DataFrame from a .hyper extract. + + :param source: Name / location of the Hyper file to be read or Hyper-API connection. + :param table: Table to read. + :param return_type: The type of DataFrame to be returned + :param process_params: Parameters to pass to the Hyper Process constructor. + """ if isinstance(table, (pt_types.TableauName, pt_types.TableauTableName)): tbl = str(table) elif isinstance(table, tuple): @@ -65,7 +79,13 @@ def frames_from_hyper( return_type: Literal["pandas", "polars", "pyarrow"] = "pandas", process_params: Optional[dict[str, str]] = None, ): - """See api.rst for documentation.""" + """ + Extracts tables from a .hyper extract. + + :param source: Name / location of the Hyper file to be read or Hyper-API connection. + :param return_type: The type of DataFrame to be returned + :param process_params: Parameters to pass to the Hyper Process constructor. + """ result = {} table_names = libpantab.get_table_names(str(source)) diff --git a/src/pantab/_writer.py b/src/pantab/_writer.py index de92841d..f056e91e 100644 --- a/src/pantab/_writer.py +++ b/src/pantab/_writer.py @@ -57,7 +57,18 @@ def frame_to_hyper( geo_columns: Optional[set[str]] = None, process_params: Optional[dict[str, str]] = None, ) -> None: - """See api.rst for documentation""" + """ + Convert a DataFrame to a .hyper extract. + + :param df: Data to be written out. + :param database: Name / location of the Hyper file to write to. + :param table: Table to write to. + :param table_mode: The mode to open the table with. Default is "w" for write, which truncates the file before writing. Another option is "a", which will append data to the file if it already contains information. + :param not_null_columns: Columns which should be considered "NOT NULL" in the target Hyper database. By default, all columns are considered nullable + :param json_columns: Columns to be written as a JSON data type + :param geo_columns: Columns to be written as a GEOGRAPHY data type + :param process_params: Parameters to pass to the Hyper Process constructor. + """ frames_to_hyper( {table: df}, database, @@ -79,7 +90,17 @@ def frames_to_hyper( geo_columns: Optional[set[str]] = None, process_params: Optional[dict[str, str]] = None, ) -> None: - """See api.rst for documentation.""" + """ + Writes multiple DataFrames to a .hyper extract. + + :param dict_of_frames: A dictionary whose keys are valid table identifiers and values are dataframes + :param database: Name / location of the Hyper file to write to. + :param table_mode: The mode to open the table with. Default is "w" for write, which truncates the file before writing. Another option is "a", which will append data to the file if it already contains information. + :param not_null_columns: Columns which should be considered "NOT NULL" in the target Hyper database. By default, all columns are considered nullable + :param json_columns: Columns to be written as a JSON data type + :param geo_columns: Columns to be written as a GEOGRAPHY data type + :param process_params: Parameters to pass to the Hyper Process constructor. + """ _validate_table_mode(table_mode) if not_null_columns is None: