mkdocs 1.5.2__tar.gz → 1.6.0__tar.gz

{mkdocs-1.5.2 → mkdocs-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: mkdocs
-Version: 1.5.2
+Version: 1.6.0
 Summary: Project documentation with Markdown.
 Project-URL: Documentation, https://www.mkdocs.org/
 Project-URL: Source, https://github.com/mkdocs/mkdocs
@@ -18,49 +18,47 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Documentation
 Classifier: Topic :: Text Processing
-Requires-Python: >=3.7
+Requires-Python: >=3.8
 Requires-Dist: click>=7.0
 Requires-Dist: colorama>=0.4; platform_system == 'Windows'
 Requires-Dist: ghp-import>=1.0
-Requires-Dist: importlib-metadata>=4.3; python_version < '3.10'
+Requires-Dist: importlib-metadata>=4.4; python_version < '3.10'
 Requires-Dist: jinja2>=2.11.1
-Requires-Dist: markdown>=3.2.1
+Requires-Dist: markdown>=3.3.6
 Requires-Dist: markupsafe>=2.0.1
 Requires-Dist: mergedeep>=1.3.4
+Requires-Dist: mkdocs-get-deps>=0.2.0
 Requires-Dist: packaging>=20.5
 Requires-Dist: pathspec>=0.11.1
-Requires-Dist: platformdirs>=2.2.0
 Requires-Dist: pyyaml-env-tag>=0.1
 Requires-Dist: pyyaml>=5.1
-Requires-Dist: typing-extensions>=3.10; python_version < '3.8'
 Requires-Dist: watchdog>=2.0
 Provides-Extra: i18n
 Requires-Dist: babel>=2.9.0; extra == 'i18n'
 Provides-Extra: min-versions
 Requires-Dist: babel==2.9.0; extra == 'min-versions'
 Requires-Dist: click==7.0; extra == 'min-versions'
-Requires-Dist: colorama==0.4; platform_system == 'Windows' and extra == 'min-versions'
+Requires-Dist: colorama==0.4; (platform_system == 'Windows') and extra == 'min-versions'
 Requires-Dist: ghp-import==1.0; extra == 'min-versions'
-Requires-Dist: importlib-metadata==4.3; python_version < '3.10' and extra == 'min-versions'
+Requires-Dist: importlib-metadata==4.4; (python_version < '3.10') and extra == 'min-versions'
 Requires-Dist: jinja2==2.11.1; extra == 'min-versions'
-Requires-Dist: markdown==3.2.1; extra == 'min-versions'
+Requires-Dist: markdown==3.3.6; extra == 'min-versions'
 Requires-Dist: markupsafe==2.0.1; extra == 'min-versions'
 Requires-Dist: mergedeep==1.3.4; extra == 'min-versions'
+Requires-Dist: mkdocs-get-deps==0.2.0; extra == 'min-versions'
 Requires-Dist: packaging==20.5; extra == 'min-versions'
 Requires-Dist: pathspec==0.11.1; extra == 'min-versions'
-Requires-Dist: platformdirs==2.2.0; extra == 'min-versions'
 Requires-Dist: pyyaml-env-tag==0.1; extra == 'min-versions'
 Requires-Dist: pyyaml==5.1; extra == 'min-versions'
-Requires-Dist: typing-extensions==3.10; python_version < '3.8' and extra == 'min-versions'
 Requires-Dist: watchdog==2.0; extra == 'min-versions'
 Description-Content-Type: text/markdown
 

{mkdocs-1.5.2 → mkdocs-1.6.0}/mkdocs/__init__.py

@@ -2,4 +2,4 @@
 
 
 # For acceptable version formats, see https://www.python.org/dev/peps/pep-0440/
-__version__ = '1.5.2'
+__version__ = '1.6.0'

{mkdocs-1.5.2 → mkdocs-1.6.0}/mkdocs/__main__.py

@@ -89,13 +89,11 @@ class State:
 
     def __init__(self, log_name='mkdocs', level=logging.INFO):
         self.logger = logging.getLogger(log_name)
-        # Don't restrict level on logger; use handler
-        self.logger.setLevel(1)
+        self.logger.setLevel(level)
         self.logger.propagate = False
 
         self.stream = logging.StreamHandler()
         self.stream.setFormatter(ColorFormatter())
-        self.stream.setLevel(level)
         self.stream.name = 'MkDocsStreamHandler'
         self.logger.addHandler(self.stream)
 
@@ -110,6 +108,7 @@ config_help = (
     "Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin."
 )
 dev_addr_help = "IP address and port to serve documentation locally (default: localhost:8000)"
+serve_open_help = "Open the website in a Web browser after the initial build finishes."
 strict_help = "Enable strict mode. This will cause MkDocs to abort the build on any warnings."
 theme_help = "The theme to use when building your documentation."
 theme_choices = sorted(utils.get_theme_names())
@@ -161,7 +160,7 @@ def verbose_option(f):
     def callback(ctx, param, value):
         state = ctx.ensure_object(State)
         if value:
-            state.stream.setLevel(logging.DEBUG)
+            state.logger.setLevel(logging.DEBUG)
 
     return click.option(
         '-v',
@@ -177,7 +176,7 @@ def quiet_option(f):
     def callback(ctx, param, value):
         state = ctx.ensure_object(State)
         if value:
-            state.stream.setLevel(logging.ERROR)
+            state.logger.setLevel(logging.ERROR)
 
     return click.option(
         '-q',
@@ -244,13 +243,12 @@ PKG_DIR = os.path.dirname(os.path.abspath(__file__))
 @common_options
 @color_option
 def cli():
-    """
-    MkDocs - Project documentation with Markdown.
-    """
+    """MkDocs - Project documentation with Markdown."""
 
 
 @cli.command(name="serve")
 @click.option('-a', '--dev-addr', help=dev_addr_help, metavar='<IP:PORT>')
+@click.option('-o', '--open', 'open_in_browser', help=serve_open_help, is_flag=True)
 @click.option('--no-livereload', 'livereload', flag_value=False, help=no_reload_help)
 @click.option('--livereload', 'livereload', flag_value=True, default=True, hidden=True)
 @click.option('--dirtyreload', 'build_type', flag_value='dirty', hidden=True)
@@ -263,7 +261,7 @@ def cli():
 @common_config_options
 @common_options
 def serve_command(**kwargs):
-    """Run the builtin development server"""
+    """Run the builtin development server."""
     from mkdocs.commands import serve
 
     _enable_warnings()
@@ -276,7 +274,7 @@ def serve_command(**kwargs):
 @click.option('-d', '--site-dir', type=click.Path(), help=site_dir_help)
 @common_options
 def build_command(clean, **kwargs):
-    """Build the MkDocs documentation"""
+    """Build the MkDocs documentation."""
     from mkdocs.commands import build
 
     _enable_warnings()
@@ -303,7 +301,7 @@ def build_command(clean, **kwargs):
 def gh_deploy_command(
     clean, message, remote_branch, remote_name, force, no_history, ignore_version, shell, **kwargs
 ):
-    """Deploy your documentation to GitHub Pages"""
+    """Deploy your documentation to GitHub Pages."""
     from mkdocs.commands import build, gh_deploy
 
     _enable_warnings()
@@ -329,19 +327,26 @@ def gh_deploy_command(
 @click.option(
     '-p',
     '--projects-file',
-    default='https://raw.githubusercontent.com/mkdocs/catalog/main/projects.yaml',
+    default=None,
     help=projects_file_help,
     show_default=True,
 )
 def get_deps_command(config_file, projects_file):
-    """Show required PyPI packages inferred from plugins in mkdocs.yml"""
-    from mkdocs.commands import get_deps
+    """Show required PyPI packages inferred from plugins in mkdocs.yml."""
+    from mkdocs_get_deps import get_deps, get_projects_file
+
+    from mkdocs.config.base import _open_config_file
 
     warning_counter = utils.CountHandler()
     warning_counter.setLevel(logging.WARNING)
     logging.getLogger('mkdocs').addHandler(warning_counter)
 
-    get_deps.get_deps(projects_file_url=projects_file, config_file_path=config_file)
+    with get_projects_file(projects_file) as p:
+        with _open_config_file(config_file) as f:
+            deps = get_deps(config_file=f, projects_file=p)
+
+    for dep in deps:
+        print(dep)  # noqa: T201
 
     if warning_counter.get_counts():
         sys.exit(1)
@@ -351,7 +356,7 @@ def get_deps_command(config_file, projects_file):
 @click.argument("project_directory")
 @common_options
 def new_command(project_directory):
-    """Create a new MkDocs project"""
+    """Create a new MkDocs project."""
     from mkdocs.commands import new
 
     new.new(project_directory)

{mkdocs-1.5.2 → mkdocs-1.6.0}/mkdocs/commands/build.py

@@ -13,17 +13,15 @@ from jinja2.exceptions import TemplateNotFound
 import mkdocs
 from mkdocs import utils
 from mkdocs.exceptions import Abort, BuildError
-from mkdocs.structure.files import File, Files, InclusionLevel, _set_exclusions, get_files
+from mkdocs.structure.files import File, Files, InclusionLevel, get_files, set_exclusions
 from mkdocs.structure.nav import Navigation, get_navigation
 from mkdocs.structure.pages import Page
-from mkdocs.utils import DuplicateFilter  # noqa - legacy re-export
+from mkdocs.utils import DuplicateFilter  # noqa: F401 - legacy re-export
 from mkdocs.utils import templates
 
 if TYPE_CHECKING:
     from mkdocs.config.defaults import MkDocsConfig
 
-if TYPE_CHECKING:
-    from mkdocs.livereload import LiveReloadServer
 
 log = logging.getLogger(__name__)
 
@@ -35,9 +33,7 @@ def get_context(
     page: Page | None = None,
     base_url: str = '',
 ) -> templates.TemplateContext:
-    """
-    Return the template context for a given page or template.
-    """
+    """Return the template context for a given page or template."""
     if page is not None:
         base_url = utils.get_relative_url('.', page.url)
 
@@ -65,9 +61,7 @@ def get_context(
 def _build_template(
     name: str, template: jinja2.Template, files: Files, config: MkDocsConfig, nav: Navigation
 ) -> str:
-    """
-    Return rendered output for given template as a string.
-    """
+    """Return rendered output for given template as a string."""
     # Run `pre_template` plugin events.
     template = config.plugins.on_pre_template(template, template_name=name, config=config)
 
@@ -98,7 +92,6 @@ def _build_theme_template(
     template_name: str, env: jinja2.Environment, files: Files, config: MkDocsConfig, nav: Navigation
 ) -> None:
     """Build a template using the theme environment."""
-
     log.debug(f"Building theme template: {template_name}")
 
     try:
@@ -117,7 +110,9 @@ def _build_theme_template(
             log.debug(f"Gzipping template: {template_name}")
             gz_filename = f'{output_path}.gz'
             with open(gz_filename, 'wb') as f:
-                timestamp = utils.get_build_timestamp()
+                timestamp = utils.get_build_timestamp(
+                    pages=[f.page for f in files.documentation_pages() if f.page is not None]
+                )
                 with gzip.GzipFile(
                     fileobj=f, filename=gz_filename, mode='wb', mtime=timestamp
                 ) as gz_buf:
@@ -128,7 +123,6 @@ def _build_theme_template(
 
 def _build_extra_template(template_name: str, files: Files, config: MkDocsConfig, nav: Navigation):
     """Build user templates which are not part of the theme."""
-
     log.debug(f"Building extra template: {template_name}")
 
     file = files.get_file_from_path(template_name)
@@ -137,8 +131,7 @@ def _build_extra_template(template_name: str, files: Files, config: MkDocsConfig
         return
 
     try:
-        with open(file.abs_src_path, encoding='utf-8', errors='strict') as f:
-            template = jinja2.Template(f.read())
+        template = jinja2.Template(file.content_string)
     except Exception as e:
         log.warning(f"Error reading template '{template_name}': {e}")
         return
@@ -153,7 +146,6 @@ def _build_extra_template(template_name: str, files: Files, config: MkDocsConfig
 
 def _populate_page(page: Page, config: MkDocsConfig, files: Files, dirty: bool = False) -> None:
     """Read page content from docs_dir and render Markdown."""
-
     config._current_page = page
     try:
         # When --dirty is used, only read the page if the file has been modified since the
@@ -200,7 +192,6 @@ def _build_page(
     excluded: bool = False,
 ) -> None:
     """Pass a Page to theme template and write output to site_dir."""
-
     config._current_page = page
     try:
         # When --dirty is used, only build the page if the file has been modified since the
@@ -255,11 +246,8 @@ def _build_page(
         config._current_page = None
 
 
-def build(
-    config: MkDocsConfig, live_server: LiveReloadServer | None = None, dirty: bool = False
-) -> None:
+def build(config: MkDocsConfig, *, serve_url: str | None = None, dirty: bool = False) -> None:
     """Perform a full site build."""
-
     logger = logging.getLogger('mkdocs')
 
     # Add CountHandler for strict mode
@@ -268,7 +256,7 @@ def build(
     if config.strict:
         logging.getLogger('mkdocs').addHandler(warning_counter)
 
-    inclusion = InclusionLevel.all if live_server else InclusionLevel.is_included
+    inclusion = InclusionLevel.is_in_serve if serve_url else InclusionLevel.is_included
 
     try:
         start = time.monotonic()
@@ -289,7 +277,7 @@ def build(
                 " links within your site. This option is designed for site development purposes only."
             )
 
-        if not live_server:  # pragma: no cover
+        if not serve_url:  # pragma: no cover
             log.info(f"Building documentation to directory: {config.site_dir}")
             if dirty and site_directory_contains_stale_files(config.site_dir):
                 log.info("The directory contains stale files. Use --clean to remove them.")
@@ -303,7 +291,7 @@ def build(
         # Run `files` plugin events.
         files = config.plugins.on_files(files, config=config)
         # If plugins have added files but haven't set their inclusion level, calculate it again.
-        _set_exclusions(files._files, config)
+        set_exclusions(files, config)
 
         nav = get_navigation(files, config)
 
@@ -314,16 +302,16 @@ def build(
         excluded = []
         for file in files.documentation_pages(inclusion=inclusion):
             log.debug(f"Reading: {file.src_uri}")
-            if file.page is None and file.inclusion.is_excluded():
-                if live_server:
-                    excluded.append(urljoin(live_server.url, file.url))
+            if file.page is None and file.inclusion.is_not_in_nav():
+                if serve_url and file.inclusion.is_excluded():
+                    excluded.append(urljoin(serve_url, file.url))
                 Page(None, file, config)
             assert file.page is not None
             _populate_page(file.page, config, files, dirty)
         if excluded:
             log.info(
                 "The following pages are being built only for the preview "
-                "but will be excluded from `mkdocs build` per `exclude_docs`:\n  - "
+                "but will be excluded from `mkdocs build` per `draft_docs` config:\n  - "
                 + "\n  - ".join(excluded)
             )
 
@@ -350,11 +338,15 @@ def build(
                 file.page, config, doc_files, nav, env, dirty, excluded=file.inclusion.is_excluded()
             )
 
+        log_level = config.validation.links.anchors
+        for file in doc_files:
+            assert file.page is not None
+            file.page.validate_anchor_links(files=files, log_level=log_level)
+
         # Run `post_build` plugin events.
         config.plugins.on_post_build(config=config)
 
-        counts = warning_counter.get_counts()
-        if counts:
+        if counts := warning_counter.get_counts():
             msg = ', '.join(f'{v} {k.lower()}s' for k, v in counts)
             raise Abort(f'Aborted with {msg} in strict mode!')
 
@@ -374,5 +366,4 @@ def build(
 
 def site_directory_contains_stale_files(site_directory: str) -> bool:
     """Check if the site directory contains stale files from a previous build."""
-
-    return True if os.path.exists(site_directory) and os.listdir(site_directory) else False
+    return bool(os.path.exists(site_directory) and os.listdir(site_directory))

{mkdocs-1.5.2 → mkdocs-1.6.0}/mkdocs/commands/gh_deploy.py

@@ -6,7 +6,7 @@ import re
 import subprocess
 from typing import TYPE_CHECKING
 
-import ghp_import
+import ghp_import  # type: ignore
 from packaging import version
 
 import mkdocs

{mkdocs-1.5.2 → mkdocs-1.6.0}/mkdocs/commands/serve.py

@@ -7,12 +7,9 @@ from os.path import isdir, isfile, join
 from typing import TYPE_CHECKING
 from urllib.parse import urlsplit
 
-import jinja2.exceptions
-
 from mkdocs.commands.build import build
 from mkdocs.config import load_config
-from mkdocs.exceptions import Abort
-from mkdocs.livereload import LiveReloadServer
+from mkdocs.livereload import LiveReloadServer, _serve_url
 
 if TYPE_CHECKING:
     from mkdocs.config.defaults import MkDocsConfig
@@ -26,10 +23,12 @@ def serve(
     build_type: str | None = None,
     watch_theme: bool = False,
     watch: list[str] = [],
+    *,
+    open_in_browser: bool = False,
     **kwargs,
 ) -> None:
     """
-    Start the MkDocs development server
+    Start the MkDocs development server.
 
     By default it will serve the documentation on http://localhost:8000/ and
     it will rebuild the documentation and refresh the page automatically
@@ -40,9 +39,6 @@ def serve(
     # string is returned. And it makes MkDocs temp dirs easier to identify.
     site_dir = tempfile.mkdtemp(prefix='mkdocs_')
 
-    def mount_path(config: MkDocsConfig):
-        return urlsplit(config.site_url or '/').path
-
     def get_config():
         config = load_config(
             config_file=config_file,
@@ -50,7 +46,6 @@ def serve(
             **kwargs,
         )
         config.watch.extend(watch)
-        config.site_url = f'http://{config.dev_addr}{mount_path(config)}'
         return config
 
     is_clean = build_type == 'clean'
@@ -59,16 +54,20 @@ def serve(
     config = get_config()
     config.plugins.on_startup(command=('build' if is_clean else 'serve'), dirty=is_dirty)
 
+    host, port = config.dev_addr
+    mount_path = urlsplit(config.site_url or '/').path
+    config.site_url = serve_url = _serve_url(host, port, mount_path)
+
     def builder(config: MkDocsConfig | None = None):
         log.info("Building documentation...")
         if config is None:
             config = get_config()
+            config.site_url = serve_url
 
-        build(config, live_server=None if is_clean else server, dirty=is_dirty)
+        build(config, serve_url=None if is_clean else serve_url, dirty=is_dirty)
 
-    host, port = config.dev_addr
     server = LiveReloadServer(
-        builder=builder, host=host, port=port, root=site_dir, mount_path=mount_path(config)
+        builder=builder, host=host, port=port, root=site_dir, mount_path=mount_path
     )
 
     def error_handler(code) -> bytes | None:
@@ -102,17 +101,11 @@ def serve(
                 server.watch(item)
 
         try:
-            server.serve()
+            server.serve(open_in_browser=open_in_browser)
         except KeyboardInterrupt:
             log.info("Shutting down...")
         finally:
             server.shutdown()
-    except jinja2.exceptions.TemplateError:
-        # This is a subclass of OSError, but shouldn't be suppressed.
-        raise
-    except OSError as e:  # pragma: no cover
-        # Avoid ugly, unhelpful traceback
-        raise Abort(f'{type(e).__name__}: {e}')
     finally:
         config.plugins.on_shutdown()
         if isdir(site_dir):

{mkdocs-1.5.2 → mkdocs-1.6.0}/mkdocs/config/base.py

@@ -51,7 +51,7 @@ class BaseConfigOption(Generic[T]):
     def default(self, value):
         self._default = value
 
-    def validate(self, value: object) -> T:
+    def validate(self, value: object, /) -> T:
         return self.run_validation(value)
 
     def reset_warnings(self) -> None:
@@ -64,7 +64,7 @@ class BaseConfigOption(Generic[T]):
         The pre-validation process method should be implemented by subclasses.
         """
 
-    def run_validation(self, value: object):
+    def run_validation(self, value: object, /):
         """
         Perform validation for a value.
 
@@ -190,6 +190,7 @@ class Config(UserDict):
                 config_option.reset_warnings()
             except ValidationError as e:
                 failed.append((key, e))
+                break
 
         for key in set(self.keys()) - self._schema_keys:
             warnings.append((key, f"Unrecognised configuration name: {key}"))
@@ -243,7 +244,6 @@ class Config(UserDict):
 
     def load_dict(self, patch: dict) -> None:
         """Load config options from a dictionary."""
-
         if not isinstance(patch, dict):
             raise exceptions.ConfigurationError(
                 "The configuration is invalid. Expected a key-"
@@ -272,18 +272,14 @@ class Config(UserDict):
 
 @functools.lru_cache(maxsize=None)
 def get_schema(cls: type) -> PlainConfigSchema:
-    """
-    Extract ConfigOptions defined in a class (used just as a container) and put them into a schema tuple.
-    """
+    """Extract ConfigOptions defined in a class (used just as a container) and put them into a schema tuple."""
     if issubclass(cls, Config):
         return cls._schema
     return tuple((k, v) for k, v in cls.__dict__.items() if isinstance(v, BaseConfigOption))
 
 
 class LegacyConfig(Config):
-    """
-    A configuration object for plugins, as just a dict without type-safe attribute access.
-    """
+    """A configuration object for plugins, as just a dict without type-safe attribute access."""
 
     def __init__(self, schema: PlainConfigSchema, config_file_path: str | None = None):
         self._schema = tuple((k, v) for k, v in schema)  # Re-create just for validation
@@ -345,7 +341,7 @@ def load_config(
     config_file: str | IO | None = None, *, config_file_path: str | None = None, **kwargs
 ) -> MkDocsConfig:
     """
-    Load the configuration for a given file object or name
+    Load the configuration for a given file object or name.
 
     The config_file can either be a file object, string or None. If it is None
     the default `mkdocs.yml` filename will loaded.
@@ -366,7 +362,7 @@ def load_config(
         from mkdocs.config.defaults import MkDocsConfig
 
         if config_file_path is None:
-            if fd is not sys.stdin.buffer:
+            if sys.stdin and fd is not sys.stdin.buffer:
                 config_file_path = getattr(fd, 'name', None)
         cfg = MkDocsConfig(config_file_path=config_file_path)
         # load the config file
@@ -387,7 +383,7 @@ def load_config(
         log.debug(f"Config value '{key}' = {value!r}")
 
     if len(errors) > 0:
-        raise exceptions.Abort(f"Aborted with {len(errors)} configuration errors!")
+        raise exceptions.Abort("Aborted with a configuration error!")
     elif cfg.strict and len(warnings) > 0:
         raise exceptions.Abort(
             f"Aborted with {len(warnings)} configuration warnings in 'strict' mode!"