refactor: Move extension entrypoint from ext.py to __init__.py

Then it can be consistency with other sphinxnotes projects.

Author: SilverRainZ

docs/conf.py

@@ -152,7 +152,7 @@
 # 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.
 sys.path.insert(0, os.path.abspath('../src/sphinxnotes'))
-extensions.append('snippet.ext')
+extensions.append('snippet')
 
 # DOG FOOD CONFIGURATION START
 

src/sphinxnotes/snippet/__init__.py

@@ -0,0 +1,36 @@
+"""
+sphinxnotes.snippet
+~~~~~~~~~~~~~~~~~~~
+
+Sphinx extension entrypoint.
+
+:copyright: Copyright 2024 Shengyu Zhang
+:license: BSD, see LICENSE for details.
+"""
+
+
+def setup(app):
+    # **WARNING**: We don't import these packages globally, because the current
+    # package (sphinxnotes.snippet) is always resloved when importing
+    # sphinxnotes.snippet.*. If we import packages here, eventually we will
+    # load a lot of packages from the Sphinx. It will seriously **SLOW DOWN**
+    # the startup time of our CLI tool (sphinxnotes.snippet.cli).
+    #
+    # .. seealso:: https://github.com/sphinx-notes/snippet/pull/31
+    from .ext import (
+        SnippetBuilder,
+        on_config_inited,
+        on_env_get_outdated,
+        on_doctree_resolved,
+        on_builder_finished,
+    )
+
+    app.add_builder(SnippetBuilder)
+
+    app.add_config_value('snippet_config', {}, '')
+    app.add_config_value('snippet_patterns', {'*': ['.*']}, '')
+
+    app.connect('config-inited', on_config_inited)
+    app.connect('env-get-outdated', on_env_get_outdated)
+    app.connect('doctree-resolved', on_doctree_resolved)
+    app.connect('build-finished', on_builder_finished)

src/sphinxnotes/snippet/cli.py

@@ -2,10 +2,15 @@
 sphinxnotes.snippet.cli
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-:copyright: Copyright 2020 Shengyu Zhang
+Command line entrypoint.
+
+:copyright: Copyright 2024 Shengyu Zhang
 :license: BSD, see LICENSE for details.
 """
 
+# **NOTE**: Import new packages with caution:
+# Importing complex packages (like sphinx.*) will directly slow down the
+# startup of the CLI tool.
 from __future__ import annotations
 import sys
 import argparse
@@ -14,10 +19,8 @@
 from textwrap import dedent
 from shutil import get_terminal_size
 import posixpath
-from importlib.metadata import version
 
 from xdg.BaseDirectory import xdg_config_home
-from sphinx.util.matching import patmatch
 
 from .snippets import Document
 from .config import Config
@@ -40,7 +43,7 @@ def get_integration_file(fn: str) -> str:
     .. seealso::
 
        see ``[tool.setuptools.package-data]`` section of pyproject.toml to know
-        how files are included.
+       how files are included.
     """
     # TODO: use https://docs.python.org/3/library/importlib.resources.html#importlib.resources.files
     prefix = path.abspath(path.dirname(__file__))
@@ -62,10 +65,11 @@ def main(argv: List[str] = sys.argv[1:]):
                                        * (any)               wildcard for any snippet"""),
     )
     parser.add_argument(
-        '-v',
         '--version',
-        action='version',
-        version='%(prog)s ' + version('sphinxnotes.any'),
+        # add_argument provides action='version', but it requires a version
+        # literal and doesn't support lazily obtaining version.
+        action='store_true',
+        help="show program's version number and exit",
     )
     parser.add_argument(
         '-c', '--config', default=DEFAULT_CONFIG_FILE, help='path to configuration file'
@@ -180,6 +184,16 @@ def main(argv: List[str] = sys.argv[1:]):
     # Parse command line arguments
     args = parser.parse_args(argv)
 
+    # Print version message.
+    # See parser.add_argument('--version', ...) for more detais.
+    if args.version:
+        # NOTE: Importing is slow, do it on demand.
+        from importlib.metadata import version
+
+        pkgname = 'sphinxnotes.snippet'
+        print(pkgname, version(pkgname))
+        parser.exit()
+
     # Load config from file
     if args.config == DEFAULT_CONFIG_FILE and not path.isfile(DEFAULT_CONFIG_FILE):
         print(
@@ -223,6 +237,9 @@ def _on_command_stat(args: argparse.Namespace):
 def _filter_list_items(
     cache: Cache, tags: str, docname_glob: str
 ) -> Iterable[Tuple[IndexID, Index]]:
+    # NOTE: Importing is slow, do it on demand.
+    from sphinx.util.matching import patmatch
+
     for index_id, index in cache.indexes.items():
         # Filter by tags.
         if index[0] not in tags and '*' not in tags:

src/sphinxnotes/snippet/ext.py

@@ -1,10 +1,10 @@
 """
-sphinxnotes.ext.snippet
+sphinxnotes.snippet.ext
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Sphinx extension for sphinxnotes.snippet.
+Sphinx extension implementation, but the entrypoint is located at __init__.py.
 
-:copyright: Copyright 2021 Shengyu Zhang
+:copyright: Copyright 2024 Shengyu Zhang
 :license: BSD, see LICENSE for details.
 """
 
@@ -206,15 +206,3 @@ def _format_modified_time(timestamp: float) -> str:
     """Return an RFC 3339 formatted string representing the given timestamp."""
     seconds, fraction = divmod(timestamp, 1)
     return time.strftime('%Y-%m-%d %H:%M:%S', time.gmtime(seconds)) + f'.{fraction:.3f}'
-
-
-def setup(app: Sphinx):
-    app.add_builder(SnippetBuilder)
-
-    app.add_config_value('snippet_config', {}, '')
-    app.add_config_value('snippet_patterns', {'*': ['.*']}, '')
-
-    app.connect('config-inited', on_config_inited)
-    app.connect('env-get-outdated', on_env_get_outdated)
-    app.connect('doctree-resolved', on_doctree_resolved)
-    app.connect('build-finished', on_builder_finished)