Redo Sphinx documentation

dgilman · Feb 10, 2024 · 2f53d97 · 2f53d97
1 parent a614452
commit 2f53d97
Show file tree

Hide file tree

Showing 10 changed files with 144 additions and 312 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,9 +1,10 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -16,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,38 @@
+.. mdinclude:: ../README.md
+
+.. module:: gspread_asyncio
+
+API reference
+=============
+
+Exceptions
+----------
+The :mod:`gspread_asyncio` module does not have any exceptions of its own, it instead propagates exceptions thrown from within :mod:`gspread` calls. These are all derived from a base class :exc:`gspread.exceptions.GSpreadException` and it is recommended that you catch and handle these errors.
+
+Socket, network and rate limiting exceptions are handled by :mod:`gspread_asyncio` internally. The defaults are sensible but you can subclass several methods of :mod:`~gspread_asyncio.AsyncioGspreadClientManager` if you need to customize that behavior.
+
+
+AsyncioGspreadClientManager
+---------------------------
+.. autoclass:: AsyncioGspreadClientManager
+   :members:
+
+AsyncioGspreadClient
+--------------------
+.. autoclass:: AsyncioGspreadClient
+   :members:
+
+AsyncioGspreadSpreadsheet
+-------------------------
+.. autoclass:: AsyncioGspreadSpreadsheet
+   :members:
+
+AsyncioGspreadWorksheet
+-----------------------
+.. autoclass:: AsyncioGspreadWorksheet
+   :members:
+
+
+Cell
+----
+See :class:`gspread.cell.Cell`.
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,49 +1,26 @@
-# -*- coding: utf-8 -*-
-#
 # Configuration file for the Sphinx documentation builder.
 #
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import datetime
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import os
 import sys
 
 sys.path.insert(0, os.path.abspath(".."))
 
-
 TODAY = datetime.date.today()
 
-# -- Project information -----------------------------------------------------
-
 project = "gspread_asyncio"
 copyright = f"{TODAY.year}, David Gilman"
 author = "David Gilman"
 
-# The short X.Y version
-version = ""
-# The full version, including alpha/beta/rc tags
-release = ""
-
-
 # -- General configuration ---------------------------------------------------
-suppress_warnings = ["toc.circular"]
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
@@ -52,162 +29,26 @@
     "m2r2",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
-
-# The master toctree document.
-master_doc = "index"
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = "en"
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
-
-
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = "alabaster"
+html_static_path = ["_static"]
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
 html_theme_options = {
     "description": "An asyncio API for Google Spreadsheets",
     "github_button": True,
     "github_repo": "gspread_asyncio",
     "github_user": "dgilman",
     "fixed_sidebar": True,
 }
-toc_object_entries = False
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "searchbox.html",
-    ]
-}
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "gspread_asynciodoc"
-
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (
-        master_doc,
-        "gspread_asyncio.tex",
-        "gspread\\_asyncio Documentation",
-        "David Gilman",
-        "manual",
-    ),
-]
-
-
-# -- Options for manual page output ------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, "gspread_asyncio", "gspread_asyncio Documentation", [author], 1)
-]
-
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "gspread_asyncio",
-        "gspread_asyncio Documentation",
-        author,
-        "gspread_asyncio",
-        "One line description of project.",
-        "Miscellaneous",
-    ),
-]
-
-
-# -- Options for Epub output -------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = project
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#
-# epub_identifier = ''
-
-# A unique identification for the text.
-#
-# epub_uid = ''
-
-# A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
-
-
-# -- Extension configuration -------------------------------------------------
 
 # -- Options for intersphinx extension ---------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
 
-# Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "oauth2client": ("https://oauth2client.readthedocs.io/en/latest/", None),
@@ -216,5 +57,4 @@
     "google-auth": ("https://google-auth.readthedocs.io/en/latest/", None),
 }
 
-
 autodoc_typehints = "none"
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,47 +1,16 @@
-.. toctree::
-   :hidden:
-   :maxdepth: 5
-
-   index
-
-.. mdinclude:: ../README.md
-
-.. module:: gspread_asyncio
-
-API reference
-=============
-
-Exceptions
-----------
-The :mod:`gspread_asyncio` module does not have any exceptions of its own, it instead propagates exceptions thrown from within :mod:`gspread` calls. These are all derived from a base class :exc:`gspread.exceptions.GSpreadException` and it is recommended that you catch and handle these errors.
+.. gspread_asyncio documentation master file, created by
+   sphinx-quickstart on Sat Feb 10 14:11:32 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
 
-Socket, network and rate limiting exceptions are handled by :mod:`gspread_asyncio` internally. The defaults are sensible but you can subclass several methods of :mod:`~gspread_asyncio.AsyncioGspreadClientManager` if you need to customize that behavior.
+Welcome to gspread_asyncio's documentation!
+===========================================
 
+.. toctree::
+   :maxdepth: 2
 
-AsyncioGspreadClientManager
----------------------------
-.. autoclass:: AsyncioGspreadClientManager
-   :members:
-
-AsyncioGspreadClient
---------------------
-.. autoclass:: AsyncioGspreadClient
-   :members:
-
-AsyncioGspreadSpreadsheet
--------------------------
-.. autoclass:: AsyncioGspreadSpreadsheet
-   :members:
-
-AsyncioGspreadWorksheet
------------------------
-.. autoclass:: AsyncioGspreadWorksheet
-   :members:
-
+   api
 
-Cell
-----
-See :class:`gspread.cell.Cell`.
 
 Indices and tables
 ==================

diff --git a/docs/requirements.in b/docs/requirements.in
@@ -1,4 +1,4 @@
-Sphinx==7.*
+Sphinx==7.2.*
 m2r2==0.3.3.post2
 sphinxcontrib-trio==1.1.2
 gspread==5.10.*