diff --git a/docs/_config.yml b/docs/_config.yml index 2e3a93b..71a72ab 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -5,7 +5,7 @@ title: gspread-models documentation site author: Michael Rossetti logo: logo.png -only_build_toc_files: true +only_build_toc_files: false # Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb") #exclude_patterns : [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"] @@ -23,7 +23,7 @@ html: use_issues_button: true use_repository_button: true use_edit_page_button: true - #use_multitoc_numbering : true + #extra_footer : "" # Will be displayed underneath the footer. #google_analytics_id : "" # A GA id that can be used to track book views. home_page_in_navbar: true # Whether to include your home page in the left Navigation Bar @@ -48,6 +48,19 @@ repository: path_to_book: docs # Optional path to your book, relative to the repository root branch: main # Which branch of the repository should be used when creating links (optional) -#sphinx: -# config: -# nb_execution_show_tb: True + + + + +sphinx: + extra_extensions: + # AUTO DOCUMENTATION: + # https://jupyterbook.org/en/stable/advanced/developers.html#api-reference-from-docstrings + # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html + # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration + - 'sphinx.ext.autodoc' + #- 'sphinx.ext.napoleon' + #- 'sphinx.ext.viewcode' + #config: + # add_module_names: False + # #autosummary_generate: True diff --git a/docs/_toc.yml b/docs/_toc.yml index 218c0c5..5ca9b51 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -31,6 +31,18 @@ parts: - url: https://github.com/prof-rossetti/flask-sheets-template-2024 title: Flask Sheets Web Application Template +- caption: API + chapters: + #- file: example_rst + - file: api/index + # turning off sections in sidebar nav, because of toctree on index causes duplicate sidebar nav links + #sections: + #- file: api/date_parser + #- file: api/service + #- file: api/base + ##options: + ## titlesonly: true + - caption: Contributing chapters: - file: CONTRIBUTING diff --git a/docs/api/base.rst b/docs/api/base.rst new file mode 100644 index 0000000..a231c21 --- /dev/null +++ b/docs/api/base.rst @@ -0,0 +1,35 @@ + +.. _api_base: + +Base Model +=========== + +.. automodule:: gspread_models.base + :members: + :undoc-members: +.. :show-inheritance: + + +.. Instance Methods +.. ----------------- +.. +.. .. autoclass:: gspread_models.base.BaseModel +.. :members: __init__, __iter__, created_at, row +.. +.. +.. Class Methods +.. ----------------- +.. +.. .. autoclass:: gspread_models.base.BaseModel +.. :members: bind, get_sheet, sheet +.. +.. Query Interface +.. ~~~~~~~~~~~~~~~~~ +.. +.. +.. .. autoclass:: gspread_models.base.BaseModel +.. :members: all, find, where, create, create_all, destroy_all +.. + + +Return to the :ref:`api_index`. diff --git a/docs/api/date_parser.rst b/docs/api/date_parser.rst new file mode 100644 index 0000000..207be4e --- /dev/null +++ b/docs/api/date_parser.rst @@ -0,0 +1,22 @@ + + +.. _api_date_parser: + + +Date Parser +=============== + + +.. automodule:: gspread_models.date_parser + :members: + :undoc-members: +.. :show-inheritance: + + +.. .. autoclass:: gspread_models.date_parser.DateParser +.. :members: +.. :undoc-members: +.. :show-inheritance: + + +Return to the :ref:`api_index`. diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..563f47f --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,46 @@ + +.. _api_index: + +API Documentation +================== + +.. toctree provides a table of contents for each of the specified python files +.. note: this also adds nav links to the left sidebar +.. see: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html + + +.. toctree:: + :maxdepth: 3 + + base + service + date_parser + + + + + + + + + + + + + + + +.. Cool stuff: +.. +.. + :ref:`genindex` +.. + :ref:`modindex` +.. + :ref:`search` + +.. +.. .. autosummary +.. :nosignatures: +.. +.. gspread_models.base +.. gspread_models.service +.. gspread_models.date_parser +.. diff --git a/docs/api/service.rst b/docs/api/service.rst new file mode 100644 index 0000000..9d670b6 --- /dev/null +++ b/docs/api/service.rst @@ -0,0 +1,21 @@ + +.. _api_service: + +Spreadsheet Service +====================== + + +.. automodule:: gspread_models.service + :members: + :undoc-members: + :show-inheritance: + + +.. .. autoclass:: gspread_models.service.SpreadsheetService +.. :members: +.. :undoc-members: +.. :show-inheritance: +.. + + +Return to the :ref:`api_index`. diff --git a/docs/example_rst.rst b/docs/example_rst.rst new file mode 100644 index 0000000..9b70048 --- /dev/null +++ b/docs/example_rst.rst @@ -0,0 +1,69 @@ +.. My Project documentation master file + +Example RST +====================================== + + + +Stuff Stuff Stuff + + + + + +Heading Level 1 +=============== + +Heading Level 2 +--------------- + +Heading Level 3 +~~~~~~~~~~~~~~~ + +Heading Level 4 ++++++++++++++++ + + + + +Lists +========= + + ++ Item A ++ Item B ++ Item C + + +1. Item A +2. Item B +3. Item C + + +Links +========= + +`OpenAI `_ + + + + + + + + +Code Blocks +============ + +Here is a code example:: + + def my_function(): + print("Hello, world!") + + +Syntax highlighted code block, using directive: + +.. code-block:: python + + def my_function(): + print("Hello, world!") diff --git a/docs/pandas_support.md b/docs/pandas_support.md index 4de4bcc..0724200 100644 --- a/docs/pandas_support.md +++ b/docs/pandas_support.md @@ -29,35 +29,29 @@ books_df.head() ## Customizing the Base Model -If you would like to integrate pandas DataFrame functionality into your child classes, you can leverage inheritence to overwrite the `all()` method of the base model, to optionally return data in DataFrame format: +It is possible to leverage inheritence to customize the behaviors of the base model, for example to create a method which returns all records in DataFrame format: ```py +from gspread_models.base import BaseModel from pandas import DataFrame class MyBaseModel(BaseModel): @classmethod - def all(cls, as_df=False): - """Fetches all records from a given sheet. Overwrites parent method to optionally use a dataframe approach. + def records_to_df(cls): + objects = cls.all() + df = DataFrame([dict(obj) for obj in objects]) + df.index = df["id"] + return df - Params : - as_df (bool) : whether or not to return the data as a DataFrame - """ - records = cls.sheet.get_all_records() - if as_df: - df = DataFrame([dict(cls(record)) for record in records]) - df.index = df["id"] - return df - else: - return [cls(record) for record in records] - - -#MyBaseModel.service = service MyBaseModel.bind(credentials_filepath="...", document_id="...") ``` +This way, the child class(es) can have DataFrame support by default: + ```py + class MyBook(MyBaseModel): SHEET_NAME = "books" @@ -66,7 +60,7 @@ class MyBook(MyBaseModel): ``` ```py -books_df = MyBook.all(as_df=True) +books_df = MyBook.records_to_df() books_df.head() #> id title author year created_at