Autodoc API Docs

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

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

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`.

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`.

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
+..

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`.

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 <https://www.openai.com>`_
+
+
+
+
+
+
+
+
+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!")

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