Coverage for .nox/test/lib/python3.12/site-packages/mkdocs_github_changelog/plugin.py: 96%

1"""This module contains the MkDocs plugin. 

2 

3It creates a Markdown extension ([`GithubReleaseChangelogExtension`][mkdocs_github_changelog.extension.GithubReleaseChangelogExtension]), 

4and adds it to `mkdocs` during the [`on_config` event hook](https://www.mkdocs.org/user-guide/plugins/#on_config). 

5""" 

6 

7from __future__ import annotations 

8 

9from typing import TYPE_CHECKING 

10 

11from mkdocs.config import Config 

12from mkdocs.config import config_options as opt 

13from mkdocs.plugins import BasePlugin 

14 

15from mkdocs_github_changelog.extension import GithubReleaseChangelogExtension 

16 

17if TYPE_CHECKING: 

18 from mkdocs.config.defaults import MkDocsConfig 

19 

20 

21class PluginConfig(Config): 

22 """Configuration options for `mkdocs_github_changelog` in `mkdocs.yml`.""" 

23 token = opt.Optional(opt.Type(str)) 

24 """Github token (needs repo scope for private repos, and may be worth setting for public repos due to rate limiting).""" 

25 github_api_url = opt.Optional(opt.URL()) 

26 """URL for github api endpoint if not standard github.com (This is not tested on github enterprise server).""" 

27 release_template = opt.Optional(opt.Type(str)) 

28 """Jinja2 template string to override the default.""" 

29 match = opt.Optional(opt.Type(str)) 

30 """Regex string for matching the rleease name.""" 

31 autoprocess = opt.Type(bool, default=True) 

32 """Autoprocess the release bodies for issue and username links.""" 

33 enabled = opt.Type(bool, default=True) 

34 """Enable or disable the plugin.""" 

35 

36 

37class MkdocsGithubChangelogPlugin(BasePlugin[PluginConfig]): 

38 """`mkdocs` plugin to provide the changelog from github releases.""" 

39 

40 def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None: 

41 """Initialises the extension if the plugin is enabled.""" 

42 if self.config.enabled: 

43 github_release_changelog_extension = GithubReleaseChangelogExtension(self.config) 

44 config.markdown_extensions.append(github_release_changelog_extension) # type: ignore[arg-type] 

45 return config