From fa3fc0c7cd58ee68da2eb323f0a1cbbbcad9e642 Mon Sep 17 00:00:00 2001 From: Sanhe Hu Date: Wed, 15 May 2024 01:49:23 -0400 Subject: [PATCH] fix sphinx doc --- README.rst | 13 ++- docs/source/01-Core-API/index.rst | 6 -- docs/source/02-ORM-API/index.rst | 15 +--- docs/source/03-Other-Helpers/index.rst | 6 -- docs/source/04-Custom-Types/index.rst | 8 +- docs/source/conf.py | 84 ++++++++++++------- docs/source/index.rst | 6 -- docs/source/sqlalchemy_mate/__init__.rst | 1 - docs/source/sqlalchemy_mate/_version.rst | 5 -- .../source/sqlalchemy_mate/types/__init__.rst | 2 + .../sqlalchemy_mate/types/compressed.rst | 5 ++ .../types/json_serializable.rst | 5 ++ 12 files changed, 76 insertions(+), 80 deletions(-) delete mode 100644 docs/source/sqlalchemy_mate/_version.rst create mode 100644 docs/source/sqlalchemy_mate/types/compressed.rst create mode 100644 docs/source/sqlalchemy_mate/types/json_serializable.rst diff --git a/README.rst b/README.rst index 53dc7c6..b3935ab 100644 --- 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 index e5ce12d..16a7a92 100644 --- 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 index 03fe5b2..958f8e3 100644 --- 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 index ffea998..53f26b2 100644 --- 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 `_ 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 index dead8c2..35824f1 100644 --- 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 index 4c1249a..dfc036c 100644 --- 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,25 +68,25 @@ 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. @@ -87,7 +94,7 @@ 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,8 +172,13 @@ # (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 --------------------------------------- @@ -175,8 +186,13 @@ # 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 index b419f96..8a266db 100644 --- 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? `). .. include:: ../../README.rst diff --git a/docs/source/sqlalchemy_mate/__init__.rst b/docs/source/sqlalchemy_mate/__init__.rst index cba565b..a77bd1c 100644 --- a/docs/source/sqlalchemy_mate/__init__.rst +++ b/docs/source/sqlalchemy_mate/__init__.rst @@ -13,7 +13,6 @@ sub packages and modules crud orm types - _version <_version> engine_creator io pt diff --git a/docs/source/sqlalchemy_mate/_version.rst b/docs/source/sqlalchemy_mate/_version.rst deleted file mode 100644 index cb9c7a2..0000000 --- a/docs/source/sqlalchemy_mate/_version.rst +++ /dev/null @@ -1,5 +0,0 @@ -_version -======== - -.. automodule:: sqlalchemy_mate._version - :members: \ No newline at end of file diff --git a/docs/source/sqlalchemy_mate/types/__init__.rst b/docs/source/sqlalchemy_mate/types/__init__.rst index 14470d4..4a1058f 100644 --- 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_json + json_serializable \ No newline at end of file diff --git a/docs/source/sqlalchemy_mate/types/compressed.rst b/docs/source/sqlalchemy_mate/types/compressed.rst new file mode 100644 index 0000000..acd5d5a --- /dev/null +++ b/docs/source/sqlalchemy_mate/types/compressed.rst @@ -0,0 +1,5 @@ +compressed +========== + +.. automodule:: sqlalchemy_mate.types.compressed + :members: \ No newline at end of file diff --git a/docs/source/sqlalchemy_mate/types/json_serializable.rst b/docs/source/sqlalchemy_mate/types/json_serializable.rst new file mode 100644 index 0000000..b02139e --- /dev/null +++ b/docs/source/sqlalchemy_mate/types/json_serializable.rst @@ -0,0 +1,5 @@ +json_serializable +================= + +.. automodule:: sqlalchemy_mate.types.json_serializable + :members: \ No newline at end of file