fix sphinx doc

MacHu-GWU · May 15, 2024 · fa3fc0c · fa3fc0c
1 parent 6c7f686
commit fa3fc0c
Show file tree

Hide file tree

Showing 12 changed files with 76 additions and 80 deletions.
diff --git a/README.rst b/README.rst
@@ -1,8 +1,8 @@
 .. image:: https://readthedocs.org/projects/sqlalchemy_mate/badge/?version=latest
-    :target: https://sqlalchemy_mate.readthedocs.io/index.html
+    :target: https://sqlalchemy-mate.readthedocs.io/index.html
     :alt: Documentation Status
 
-.. image:: https://github.com/MacHu-GWU/sqlalchemy_mate-project/workflows/CI/badge.svg
+.. image:: https://github.com/MacHu-GWU/sqlalchemy_mate-project/actions/workflows/main.yml/badge.svg
     :target: https://github.com/MacHu-GWU/sqlalchemy_mate-project/actions?query=workflow:CI
 
 .. image:: https://codecov.io/gh/MacHu-GWU/sqlalchemy_mate-project/branch/master/graph/badge.svg
@@ -22,15 +22,14 @@
 
 ------
 
-
 .. image:: https://img.shields.io/badge/Link-Document-blue.svg
-      :target: https://sqlalchemy_mate.readthedocs.io/index.html
+      :target: https://sqlalchemy-mate.readthedocs.io/index.html
 
 .. image:: https://img.shields.io/badge/Link-API-blue.svg
-      :target: https://sqlalchemy_mate.readthedocs.io/py-modindex.html
+      :target: https://sqlalchemy-mate.readthedocs.io/py-modindex.html
 
 .. image:: https://img.shields.io/badge/Link-Source_Code-blue.svg
-      :target: https://sqlalchemy_mate.readthedocs.io/py-modindex.html
+      :target: https://sqlalchemy-mate.readthedocs.io/py-modindex.html
 
 .. image:: https://img.shields.io/badge/Link-Install-blue.svg
       :target: `install`_
@@ -56,7 +55,6 @@ A sweet syntax sugar library simplify your in writing ``sqlalchemy`` code.
 
 Features
 ------------------------------------------------------------------------------
-
 .. contents::
     :class: this-will-duplicate-information-and-it-is-still-useful-here
     :depth: 1
@@ -65,7 +63,6 @@ Features
 
 Read Database Credential Safely
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 .. contents::
     :class: this-will-duplicate-information-and-it-is-still-useful-here
     :depth: 1

diff --git a/docs/source/01-Core-API/index.rst b/docs/source/01-Core-API/index.rst
@@ -2,12 +2,6 @@
 
 Core API
 ==============================================================================
-
-.. contents::
-    :class: this-will-duplicate-information-and-it-is-still-useful-here
-    :depth: 1
-    :local:
-
 In this section, we demonstrate the simplified version with ``sqlalchemy_mate`` to manipulate data using core API.
 
 First, let's define a table to get start, everything looks normal so far.

diff --git a/docs/source/02-ORM-API/index.rst b/docs/source/02-ORM-API/index.rst
@@ -3,31 +3,25 @@
 ORM API
 ==============================================================================
 
-.. contents::
-    :class: this-will-duplicate-information-and-it-is-still-useful-here
-    :depth: 1
-    :local:
-
 
 Extended Declarative Base
 ------------------------------------------------------------------------------
-
 ``sqlalchemy_mate.ExtendedBase`` is a Mixin class that enables many convenient method for your ORM model. In this
 
 .. code-block:: python
 
     import sqlalchemy as sa
-    from sqlalchemy.orm import declarative_base
+    import sqlalchemy.orm as orm
     import sqlalchemy_mate as sam
 
-    Base = declarative_base()
+    Base = orm.declarative_base()
 
     # add sqlalchemy_mate.ExtendedBase Mixin class
     class User(Base, sam.ExtendedBase):
         __tablename__ = "users"
 
-        id = sa.Column(sa.Integer, primary_key=True)
-        name = sa.Column(sa.String, nullable=True)
+        id: orm.Mapped[int] = orm.mapped_column(sa.Integer, primary_key=True)
+        name: orm.Mapped[str] = orm.mapped_column(sa.String, nullable=True)
 
         # put important columns here
         # you can choose to print those columns only with ``.glance()`` method.
@@ -70,7 +64,6 @@ Python dict can update values based on another dict, A data model should be able
 
 Insert, Select, Update
 ------------------------------------------------------------------------------
-
 Talk is cheap, show me the Code.
 
 .. code-block:: python

diff --git a/docs/source/03-Other-Helpers/index.rst b/docs/source/03-Other-Helpers/index.rst
@@ -3,15 +3,9 @@
 Other Helpers
 ==============================================================================
 
-.. contents::
-    :class: this-will-duplicate-information-and-it-is-still-useful-here
-    :depth: 1
-    :local:
-
 
 User Friendly Engine Creator
 ------------------------------------------------------------------------------
-
 `This sqlalchemy Official Document <https://docs.sqlalchemy.org/en/latest/core/engines.html>`_ tells you the correct connection string to use for different DB driver. Who wants to Google the API document everytime?
 
 ``sqlalchemy_mate.EngineCreator`` leveraged the IDE / Code Editor that provide a user friendly interface to pass in DB connection specs and choose the underlying python driver.

diff --git a/docs/source/04-Custom-Types/index.rst b/docs/source/04-Custom-Types/index.rst
@@ -3,11 +3,6 @@
 Custom Types
 ==============================================================================
 
-.. contents::
-    :class: this-will-duplicate-information-and-it-is-still-useful-here
-    :depth: 1
-    :local:
-
 
 Compressed String
 ------------------------------------------------------------------------------
@@ -30,6 +25,7 @@ Any JSON serializable object, if implemented ``to_json(self):`` and ``from_json(
 
 .. code-block:: python
 
+    import sqlalchemy.orm as orm
     import jsonpickle
 
     # a custom python class
@@ -44,7 +40,7 @@ Any JSON serializable object, if implemented ``to_json(self):`` and ``from_json(
         def from_json(cls, json_str: str) -> 'Computer':
             return cls(**jsonpickle.decode(json_str))
 
-    Base = declarative_base()
+    Base = orm.declarative_base()
 
     class Computer(Base):
         id = Column(Integer, primary_key)

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -23,13 +23,17 @@
 from __future__ import unicode_literals
 import os
 from datetime import datetime
-import sqlalchemy_mate
+import sqlalchemy_mate as package
+
+package_name = package.__name__
+package_author = package.__author__
+package_version = package.__version__
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+
+# needs_sphinx = '5.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -43,9 +47,12 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinxcontrib.jinja',
+    'sphinx_jinja',
     'sphinx_copybutton',
+    'sphinx_design',
+    'sphinx_search.extension',
     'docfly.directives',
+    'nbsphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -61,33 +68,33 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'sqlalchemy_mate'
-copyright = '%s, Sanhe Hu' % datetime.utcnow().year
-author = 'Sanhe Hu'
+project = package_name
+copyright = '{}, {}'.format(datetime.utcnow().year, package_author)
+author = package_author
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = sqlalchemy_mate.__version__
+version = package_version
 # The full version, including alpha/beta/rc tags.
-release = sqlalchemy_mate.__version__
+release = package_version
 
 # 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 = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'monokai'
+pygments_style = "monokai"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
@@ -97,17 +104,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'furo'
-html_theme_options = {
-    "sidebar_hide_name": False,
-}
-pygments_dark_style = "monokai"
+html_theme = "furo"
 
 # 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 = {}
+
+html_theme_options = {
+    "sidebar_hide_name": False,
+}
+pygments_dark_style = "monokai"
 
 # 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,
@@ -119,8 +125,8 @@
 html_js_files = [
     'js/sorttable.js',
 ]
-html_logo = "./_static/sqlalchemy_mate-logo.png"
-html_favicon = "./_static/sqlalchemy_mate-favicon.ico"
+html_logo = "./_static/{}-logo.png".format(package_name)
+html_favicon = "./_static/{}-favicon.ico".format(package_name)
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -140,7 +146,7 @@
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'sqlalchemy_matedoc'
+htmlhelp_basename = '{}doc'.format(package_name)
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -166,17 +172,27 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'sqlalchemy_mate.tex', 'sqlalchemy_mate Documentation',
-     u'Sanhe Hu', 'manual'),
+    (
+        master_doc,
+        '{}.tex'.format(package_name),
+        '{} Documentation'.format(package_name),
+        author,
+        '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, 'sqlalchemy_mate', 'sqlalchemy_mate Documentation',
-     [author], 1)
+    (
+        master_doc,
+        package_name,
+        '{} Documentation'.format(package_name),
+        [author],
+        1
+    )
 ]
 
 # -- Options for Texinfo output -------------------------------------------
@@ -185,9 +201,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'sqlalchemy_mate', 'sqlalchemy_mate Documentation',
-     author, 'sqlalchemy_mate', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        package_name,
+        '{} Documentation'.format(package_name),
+        author,
+        package_name,
+        'One line description of project.',
+        'Miscellaneous'
+    ),
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
@@ -201,7 +223,6 @@
     custom_style_file_content = f.read().decode("utf-8")
 rst_prolog = "\n" + custom_style_file_content + "\n"
 
-
 # Add data for Jinja2
 try:
     from sqlalchemy_mate.docs import doc_data
@@ -217,13 +238,14 @@
 # Api Reference Doc
 import docfly
 
-package_name = sqlalchemy_mate.__name__
 docfly.ApiReferenceDoc(
     conf_file=__file__,
     package_name=package_name,
     ignored_package=[
-        "%s.pkg" % package_name,
         "%s.docs" % package_name,
         "%s.tests" % package_name,
+        "%s.vendor" % package_name,
+        "%s._version" % package_name,
+        "%s.paths" % package_name,
     ]
 ).fly()
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,9 +1,3 @@
-
-.. contents::
-    :class: this-will-duplicate-information-and-it-is-still-useful-here
-    :depth: 2
-    :local:
-
 Release v\ |release| (:ref:`What's new? <release_history>`).
 
 .. include:: ../../README.rst

diff --git a/docs/source/sqlalchemy_mate/__init__.rst b/docs/source/sqlalchemy_mate/__init__.rst
@@ -13,7 +13,6 @@ sub packages and modules
     crud <crud/__init__>
     orm <orm/__init__>
     types <types/__init__>
-    _version <_version>
     engine_creator <engine_creator>
     io <io>
     pt <pt>

diff --git a/docs/source/sqlalchemy_mate/_version.rst b/docs/source/sqlalchemy_mate/_version.rst
diff --git a/docs/source/sqlalchemy_mate/types/__init__.rst b/docs/source/sqlalchemy_mate/types/__init__.rst
@@ -10,5 +10,7 @@ sub packages and modules
 .. toctree::
     :maxdepth: 1
 
+    compressed <compressed>
     compressed_json <compressed_json>
+    json_serializable <json_serializable>
 
diff --git a/docs/source/sqlalchemy_mate/types/compressed.rst b/docs/source/sqlalchemy_mate/types/compressed.rst
@@ -0,0 +1,5 @@
+compressed
+==========
+
+.. automodule:: sqlalchemy_mate.types.compressed
+    :members:
diff --git a/docs/source/sqlalchemy_mate/types/json_serializable.rst b/docs/source/sqlalchemy_mate/types/json_serializable.rst
@@ -0,0 +1,5 @@
+json_serializable
+=================
+
+.. automodule:: sqlalchemy_mate.types.json_serializable
+    :members: