Update packaging, formatting, and linting (#82)

.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Check manifest
         run: tox -e manifest
       - name: Check code quality with flake8
-        run: tox -e flake8
+        run: tox -e format,lint
       - name: Check package metadata with Pyroma
         run: tox -e pyroma
       - name: Check static typing with MyPy
@@ -34,7 +34,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ "3.12", "3.9" ]
+        python-version: [ "3.12" ]
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python-version }}

.gitignore

@@ -130,3 +130,6 @@ dmypy.json
 
 # Auto-generated docs
 docs/source/api/
+tests/resources/test_1.db
+tests/resources/test_1.json.bz2
+tests/resources/test_1.pkl.gz

docs/source/conf.py

@@ -1,43 +1,55 @@
-# -*- 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
+"""
+Configuration file for the Sphinx documentation builder.
 
-# -- Path setup --------------------------------------------------------------
+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
 
-# 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.
-#
+-- Path setup --------------------------------------------------------------
+
+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 re
 import sys
 from datetime import date
 
-sys.path.insert(0, os.path.abspath('../../src'))
+sys.path.insert(0, os.path.abspath("../../src"))
 
 # -- Project information -----------------------------------------------------
 
-project = 'pystow'
-copyright = f'{date.today().year}, Charles Tapley Hoyt'
-author = 'Charles Tapley Hoyt'
+project = "pystow"
+copyright = f"{date.today().year}, Charles Tapley Hoyt"
+author = "Charles Tapley Hoyt"
 
 # The full version, including alpha/beta/rc tags.
-release = '0.5.7-dev'
+release = "0.5.7-dev"
 
 # The short X.Y version.
 parsed_version = re.match(
-    '(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(?:-(?P<release>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+(?P<build>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?',
+    r"(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(?:-(?P<release>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+(?P<build>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?",
     release,
 )
-version = parsed_version.expand('\g<major>.\g<minor>.\g<patch>')
+version = parsed_version.expand(r"\g<major>.\g<minor>.\g<patch>")
+
+if parsed_version.group("release"):
+    tags.add("prerelease")  # noqa:F821
+
+
+# See https://about.readthedocs.com/blog/2024/07/addons-by-default/
+# Define the canonical URL if you are using a custom domain on Read the Docs
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+# See https://about.readthedocs.com/blog/2024/07/addons-by-default/
+# Tell Jinja2 templates the build is running on Read the Docs
+if os.environ.get("READTHEDOCS", "") == "True":
+    if "html_context" not in globals():
+        html_context = {}
+    html_context["READTHEDOCS"] = True
 
-if parsed_version.group('release'):
-    tags.add('prerelease')
 
 # -- General configuration ---------------------------------------------------
 
@@ -56,32 +68,37 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autosummary',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.coverage',
-    'sphinx.ext.intersphinx',
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'sphinx_autodoc_typehints',
-    'sphinx_click.ext',
-    'sphinx_automodapi.automodapi',
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx_automodapi.automodapi",
+    "sphinx_automodapi.smart_resolver",
 ]
 
+
+extensions.append("sphinx_click.ext")
+
+
 # generate autosummary pages
-# autosummary_generate = True
+autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+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'
+source_suffix = {
+    ".rst": "restructuredtext",
+}
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -96,14 +113,14 @@
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # -- 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 = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # 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
@@ -129,13 +146,13 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-if os.path.exists('logo.png'):
-    html_logo = 'logo.png'
+if os.path.exists("logo.png"):
+    html_logo = "logo.png"
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'PyStowdoc'
+htmlhelp_basename = "pystow_doc"
 
 # -- Options for LaTeX output ------------------------------------------------
 
@@ -177,8 +194,8 @@
 man_pages = [
     (
         master_doc,
-        'pystow',
-        'PyStow Documentation',
+        "pystow",
+        "PyStow Documentation",
         [author],
         1,
     ),
@@ -192,12 +209,12 @@
 texinfo_documents = [
     (
         master_doc,
-        'pystow',
-        'PyStow Documentation',
+        "pystow",
+        "PyStow Documentation",
         author,
-        'Charles Tapley Hoyt',
-        '👜 Easily pick a place to store data for your python package.',
-        'Miscellaneous',
+        "Charles Tapley Hoyt",
+        "Easily pick a place to store data for your Python code",
+        "Miscellaneous",
     ),
 ]
 
@@ -223,11 +240,21 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
+# Note: don't add trailing slashes, since sphinx adds "/objects.inv" to the end
 intersphinx_mapping = {
-    "python": ('https://docs.python.org/3/', None),
-    'rdflib': ('https://rdflib.readthedocs.io/en/latest/', None),
-    'pandas': ('https://pandas.pydata.org/pandas-docs/dev', None),
+    "python": ("https://docs.python.org/3", None),
+    "rdflib": ("https://rdflib.readthedocs.io/en/latest", None),
+    "pandas": ("https://pandas.pydata.org/docs", None),
+    "sklearn": ("https://scikit-learn.org/stable", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
 }
 
-autoclass_content = 'both'
-autodoc_member_order = 'bysource'
+autoclass_content = "both"
+
+# Don't sort alphabetically, explained at:
+# https://stackoverflow.com/questions/37209921/python-how-not-to-sort-sphinx-output-in-alphabetical-order
+autodoc_member_order = "bysource"
+
+todo_include_todos = True
+todo_emit_warnings = True