diff options
| -rw-r--r-- | .github/workflows/docs.yaml | 2 | ||||
| -rw-r--r-- | README.md | 4 | ||||
| -rw-r--r-- | docs/README.md | 4 | ||||
| -rw-r--r-- | docs/_static/changelog.css | 11 | ||||
| -rw-r--r-- | docs/_static/changelog.js | 41 | ||||
| -rw-r--r-- | docs/changelog.rst | 124 | ||||
| -rw-r--r-- | docs/conf.py | 20 | ||||
| -rw-r--r-- | docs/index.rst | 5 | ||||
| -rw-r--r-- | docs/utils.py | 50 | ||||
| -rw-r--r-- | poetry.lock | 49 | ||||
| -rw-r--r-- | pyproject.toml | 2 |
11 files changed, 289 insertions, 23 deletions
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index ad10f75f..79a96ea5 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,7 +37,7 @@ jobs: - name: Generate HTML Site run: sphinx-build -nW -j auto -b html docs docs/build - - name: Uplaod Build Artifact + - name: Upload Build Artifact uses: actions/upload-artifact@v2 with: name: docs @@ -1 +1,3 @@ -# bot-core +# bot-core ![Version] + +[Version]: https://img.shields.io/github/v/tag/python-discord/bot-core?label=latest&logo=version diff --git a/docs/README.md b/docs/README.md index fa719292..2146ce5b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,11 +38,11 @@ Refer to the [sphinx documentation][docstring-sections] for more information. Each change requires an entry in the [Changelog](./changelog.rst). Refer to the [Releases][releases] documentation for more information on the exact format and content of entries -You can use [this site][releases] to get the PR number you'll use for your entry. +You can use [this site][next] to get the PR number that'll be assigned for your entry. -[next]: https://ichard26.github.io/next-pr-number/?owner=python-discord&name=bot-core [releases]: https://releases.readthedocs.io/en/latest/concepts.html +[next]: https://ichard26.github.io/next-pr-number/?owner=python-discord&name=bot-core ## Static Builds We deploy our docs to netlify to power static previews on PRs. diff --git a/docs/_static/changelog.css b/docs/_static/changelog.css new file mode 100644 index 00000000..343792a1 --- /dev/null +++ b/docs/_static/changelog.css @@ -0,0 +1,11 @@ +[data-theme='dark'] #changelog .dark, +[data-theme='light'] #changelog .light, +[data-theme='auto'] #changelog .light { + display: inline; +} + +[data-theme='dark'] #changelog .light, +[data-theme='light'] #changelog .dark, +[data-theme='auto'] #changelog .dark { + display: none; +} diff --git a/docs/_static/changelog.js b/docs/_static/changelog.js new file mode 100644 index 00000000..94834eaa --- /dev/null +++ b/docs/_static/changelog.js @@ -0,0 +1,41 @@ +/** Update the changelog colors in dark mode */ +function changelog_color_main() { + const changelog = document.getElementById("changelog"); + + function updateEntryColor(span) { + const lightColorSpan = span; + const darkColorSpan = lightColorSpan.cloneNode(true); + + lightColorSpan.parentElement.insertBefore(darkColorSpan, lightColorSpan); + + lightColorSpan.classList.add("light"); + darkColorSpan.classList.add("dark"); + + let color; + switch (darkColorSpan.textContent) { + case "Feature": + color = "#5BF38E"; + break; + case "Support": + color = "#55A5E7"; + break; + case "Bug": + color = "#E14F4F"; + break; + default: + color = lightColorSpan.style.color; + } + + darkColorSpan.style["color"] = color; + } + + const TYPES = ["Feature", "Bug", "Support", "Breaking"]; + + if (changelog !== null) { + Array.from(changelog.getElementsByTagName("span")) + .filter(value => TYPES.includes(value.textContent)) + .forEach(updateEntryColor) + } +} + +changelog_color_main(); diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 00000000..3cee3a7a --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,124 @@ +.. See docs for details on formatting your entries + https://releases.readthedocs.io/en/latest/concepts.html + +Changelog +========= + +- :support:`79` Restore on-site changelog. + + +- :release:`7.1.0 <24th May 2022>` +- :feature:`78` Bump Discord.py to :literal-url:`4cbe8f5 <https://github.com/Rapptz/discord.py/tree/4cbe8f58e16f6a76371ce45a69e0832130d6d24f>`: + + - This fixes a bug with permission resolution when dealing with timed out members. + + +- :release:`7.0.0 <10th May 2022>` +- :bug:`75 major` Capture all characters up to a whitespace in the Discord Invite regex. +- :breaking:`75` Discord invite regex no longer returns a URL safe result, refer to documentation for safely handling it. + + +- :release:`6.4.0 <26th April 2022>` +- :feature:`72` Bump discord.py to :literal-url:`5a06fa5 <https://github.com/Rapptz/discord.py/tree/5a06fa5f3e28d2b7191722e1a84c541560008aea>`: + + - Notably, one of the commits in this bump dynamically extends the timeout of ``Guild.chunk()`` based on the number or members, so it should actually work on our guild now. + + +- :release:`6.3.2 <25th April 2022>` +- :bug:`69` Actually use ``statsd_url`` when it gets passed to ``BotBase``. + + +- :release:`6.3.1 <21st April 2022>` +- :bug:`68` Correct version number in pyproject.toml + + +- :release:`6.3.0 <21st April 2022>` +- :feature:`-` (Committed directly to main) Don't load modules starting with ``_`` + + +- :release:`6.2.0 <21st April 2022>` +- :feature:`66` Load each cog in it's own task to avoid a single cog crashing entire load process. + + +- :release:`6.1.0 <20th April 2022>` +- :feature:`65` Add ``unqualify`` to the ``botcore.utils`` namespace for use in bots that manipulate extensions. + + +- :release:`6.0.0 <19th April 2022>` +- :breaking:`64` Bump discord.py to :literal-url:`987235d <https://github.com/Rapptz/discord.py/tree/987235d5649e7c2b1a927637bab6547244ecb2cf>`: + + - This reverts a change to help command behaviour that broke our custom pagination + - This also adds basic forum channel support to discord.py + + +- :release:`5.0.4 <18th April 2022>` 63 + + .. + Feature 63 Needs to be explicitly included below because it was improperly released within a bugfix version + instead of a minor release + +- :feature:`63` Allow passing an ``api_client`` to ``BotBase.__init__`` to specify the ``botcore.site_api.APIClient`` instance to use. + + +- :release:`5.0.3 <18th April 2022>` +- :bug:`61` Reconnect to redis session on setup if it is closed. + + +- :release:`5.0.2 <5th April 2022>` +- :bug:`56` Create a dummy ``AsyncstatsdClient`` before connecting to real url, in case a connection cannot be made on init. +- :bug:`56` Move the creation of the ``asyncio.Event``, ``BotBase._guild_available`` to within the setup hook, to avoid a deprecation notice. + + +- :release:`5.0.1 <2nd April 2022>` +- :bug:`54` Move creation of BotBase's ``aiohttp.AsyncResolver`` to the async setup hook, to avoid deprecation notice + + +- :release:`5.0.0 <2nd April 2022>` +- :breaking:`42` Remove public extensions util. +- :feature:`42` Add ``BotBase``, a ``discord.ext.commands.Bot`` sub-class, which abstracts a lot of logic shared between our bots. +- :feature:`42` Add async statsd client. +- :support:`42` Bump Discord.py to latest alpha commit. + + +- :release:`4.0.0 <14th March 2022>` +- :breaking:`39` Migrate back to Discord.py 2.0. + + +- :release:`3.0.1 <5th March 2022>` +- :bug:`37` Setup log tracing when ``botcore.utils.logging`` is imported so that it can be used within botcore functions. + + +- :release:`3.0.0 <3rd March 2022>` +- :breaking:`35` Move ``apply_monkey_patches()`` directly to `botcore.utils` namespace. + + +- :release:`2.1.0 <24th February 2022>` +- :feature:`34` Port the Site API wrapper from the bot repo. + + +- :release:`2.0.0 <22nd February 2022>` +- :breaking:`35` Moved regex to ``botcore.utils`` namespace +- :breaking:`32` Migrate from discord.py 2.0a0 to disnake. +- :feature:`32` Add common monkey patches. +- :feature:`29` Port many common utilities from our bots: + + - caching + - channel + - extensions + - loggers + - members + - scheduling +- :support:`2` Added intersphinx to docs. + + +- :release:`1.2.0 <9th January 2022>` +- :feature:`12` Code block detection regex. + + +- :release:`1.1.0 <2nd December 2021>` +- :support:`2` Autogenerated docs. +- :feature:`2` Regex utility. + + +- :release:`1.0.0 <17th November 2021>` +- :feature:`1` Core package, poetry, and linting CI. diff --git a/docs/conf.py b/docs/conf.py index 8459f3fb..1cea4026 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,6 +7,7 @@ import sys from pathlib import Path import git +import releases import tomli from sphinx.application import Sphinx @@ -46,6 +47,7 @@ extensions = [ "sphinx.ext.todo", "sphinx.ext.napoleon", "sphinx_autodoc_typehints", + "releases", "sphinx.ext.linkcode", "sphinx.ext.githubpages", ] @@ -82,10 +84,9 @@ html_short_title = project html_logo = "https://raw.githubusercontent.com/python-discord/branding/main/logos/logo_full/logo_full.min.svg" html_favicon = html_logo -html_css_files = [ - "index.css", - "logo.css", -] +static = Path("_static") +html_css_files = utils.get_recursive_file_uris(static, "*.css") +html_js_files = utils.get_recursive_file_uris(static, "*.js") utils.cleanup() @@ -105,6 +106,12 @@ def skip(*args) -> bool: def setup(app: Sphinx) -> None: """Add extra hook-based autodoc configuration.""" app.connect("autodoc-skip-member", skip) + app.add_role("literal-url", utils.emphasized_url) + + # Add a `breaking` role to the changelog + releases.ISSUE_TYPES["breaking"] = "F50F10" # This is the hex for a light red color + releases.reorder_release_entries = utils.reorder_release_entries + app.add_role("breaking", releases.issues_role) ignored_modules = [ @@ -148,3 +155,8 @@ intersphinx_mapping = { # -- Options for the linkcode extension -------------------------------------- linkcode_resolve = functools.partial(utils.linkcode_resolve, SOURCE_FILE_LINK) + + +# -- Options for releases extension ------------------------------------------ +releases_github_path = REPO_LINK.removeprefix("https://github.com/") +releases_release_uri = f"{REPO_LINK}/releases/tag/v%s" diff --git a/docs/index.rst b/docs/index.rst index 98dcd611..0a375b90 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,8 +15,9 @@ Reference .. toctree:: :caption: Other: + :hidden: - Changelog <https://github.com/python-discord/bot-core/blob/main/CHANGELOG.md> + changelog Extras @@ -25,4 +26,4 @@ Extras * :ref:`genindex` * :ref:`search` * :repo-file:`Information <docs/README.md>` -* :repo-file:`Changelog <CHANGELOG.md>` +* :doc:`changelog` diff --git a/docs/utils.py b/docs/utils.py index 9116c130..aaa656c3 100644 --- a/docs/utils.py +++ b/docs/utils.py @@ -6,6 +6,10 @@ import inspect import typing from pathlib import Path +import docutils.nodes +import docutils.parsers.rst.states +import releases + PROJECT_ROOT = Path(__file__).parent.parent @@ -108,7 +112,7 @@ def __get_included() -> set[str]: try: module = importlib.import_module(module_name) except ModuleNotFoundError: - return {} + return set() _modules = {module.__name__ + ".rst"} if hasattr(module, "__all__"): @@ -118,3 +122,47 @@ def __get_included() -> set[str]: return _modules return get_all_from_module("botcore") + + +def reorder_release_entries(release_list: list[releases.Release]) -> None: + """ + Sort `releases` based on `release.type`. + + This is meant to be used as an override for `releases.reorder_release_entries` to support + custom types. + """ + order = {"breaking": 0, "feature": 1, "bug": 2, "support": 3} + for release in release_list: + release["entries"].sort(key=lambda entry: order[entry.type]) + + +def emphasized_url( + name: str, rawtext: str, text: str, lineno: int, inliner: docutils.parsers.rst.states.Inliner, *__ +) -> tuple[list, list]: + """ + Sphinx role to add hyperlinked literals. + + ReST: :literal-url:`Google <https://google.com>` + Markdown equivalent: [`Google`](https://google.com) + + Refer to https://docutils.sourceforge.io/docs/howto/rst-roles.html for details on the input and output. + """ + arguments = text.rsplit(maxsplit=1) + if len(arguments) != 2: + message = inliner.reporter.error( + f"`{name}` expects a message and a URL, formatted as: :{name}:`message <url>`", + line=lineno + ) + problem = inliner.problematic(text, rawtext, message) + return [problem], [message] + + message, url = arguments + url: str = url[1:-1] # Remove the angled brackets off the start and end + + literal = docutils.nodes.literal(rawtext, message) + return [docutils.nodes.reference(rawtext, "", literal, refuri=url)], [] + + +def get_recursive_file_uris(folder: Path, match_pattern: str) -> list[str]: + """Get the URI of any file relative to folder which matches the `match_pattern` regex.""" + return [file.relative_to(folder).as_posix() for file in folder.rglob(match_pattern)] diff --git a/poetry.lock b/poetry.lock index a6b2612e..af24501a 100644 --- a/poetry.lock +++ b/poetry.lock @@ -235,22 +235,21 @@ testing = ["pre-commit"] [[package]] name = "fakeredis" -version = "1.7.5" +version = "1.8" description = "Fake implementation of redis API for testing purposes." category = "main" optional = true -python-versions = ">=3.7" +python-versions = ">=3.7,<4.0" [package.dependencies] -lupa = {version = "*", optional = true, markers = "extra == \"lua\""} -packaging = "*" +lupa = {version = ">=1.13,<2.0", optional = true, markers = "extra == \"lua\""} redis = "<=4.3.1" -six = ">=1.12" -sortedcontainers = "*" +six = ">=1.16.0,<2.0.0" +sortedcontainers = ">=2.4.0,<3.0.0" [package.extras] -aioredis = ["aioredis"] -lua = ["lupa"] +aioredis = ["aioredis (>=2.0.1,<3.0.0)"] +lua = ["lupa (>=1.13,<2.0)"] [[package]] name = "filelock" @@ -769,6 +768,18 @@ hiredis = ["hiredis (>=1.0.0)"] ocsp = ["cryptography (>=36.0.1)", "pyopenssl (==20.0.1)", "requests (>=2.26.0)"] [[package]] +name = "releases" +version = "1.6.3" +description = "A Sphinx extension for changelog manipulation" +category = "dev" +optional = false +python-versions = "*" + +[package.dependencies] +semantic-version = "<2.7" +sphinx = ">=1.3" + +[[package]] name = "requests" version = "2.27.1" description = "Python HTTP for Humans." @@ -787,6 +798,14 @@ socks = ["PySocks (>=1.5.6,!=1.5.7)", "win-inet-pton"] use_chardet_on_py3 = ["chardet (>=3.0.2,<5)"] [[package]] +name = "semantic-version" +version = "2.6.0" +description = "A library implementing the 'SemVer' scheme." +category = "dev" +optional = false +python-versions = "*" + +[[package]] name = "six" version = "1.16.0" description = "Python 2 and 3 compatibility utilities" @@ -1059,7 +1078,7 @@ async-rediscache = ["async-rediscache"] [metadata] lock-version = "1.1" python-versions = "3.9.*" -content-hash = "437a2dc7523efe2e6031432a5935451611ba427a9314bb0287f1a9cbb4466d77" +content-hash = "b4b7d5cf3933b4237051c02050f3dadefa58ad39e5cebc7434f097b7315ea179" [metadata.files] aiohttp = [ @@ -1249,8 +1268,8 @@ execnet = [ {file = "execnet-1.9.0.tar.gz", hash = "sha256:8f694f3ba9cc92cab508b152dcfe322153975c29bda272e2fd7f3f00f36e47c5"}, ] fakeredis = [ - {file = "fakeredis-1.7.5-py3-none-any.whl", hash = "sha256:c4ca2be686e7e7637756ccc7dcad8472a5e4866b065431107d7a4b7a250d4e6f"}, - {file = "fakeredis-1.7.5.tar.gz", hash = "sha256:49375c630981dd4045d9a92e2709fcd4476c91f927e0228493eefa625e705133"}, + {file = "fakeredis-1.8-py3-none-any.whl", hash = "sha256:65dcd78c0cd29d17daccce9f58698f6ab61ad7a404eab373fcad2b76fe8db03d"}, + {file = "fakeredis-1.8.tar.gz", hash = "sha256:cbf8d74ae06672d40b2fa88b9ee4f1d6efd56b06b2e7f0be2c639647f00643f1"}, ] filelock = [ {file = "filelock-3.7.0-py3-none-any.whl", hash = "sha256:c7b5fdb219b398a5b28c8e4c1893ef5f98ece6a38c6ab2c22e26ec161556fed6"}, @@ -1712,10 +1731,18 @@ redis = [ {file = "redis-4.3.1-py3-none-any.whl", hash = "sha256:84316970995a7adb907a56754d2b92d88fc2d252963dc5ac34c88f0f1a22c25d"}, {file = "redis-4.3.1.tar.gz", hash = "sha256:94b617b4cd296e94991146f66fc5559756fbefe9493604f0312e4d3298ac63e9"}, ] +releases = [ + {file = "releases-1.6.3-py2.py3-none-any.whl", hash = "sha256:cb3435ba372a6807433800fbe473760cfa781171513f670f3c4b76983ac80f18"}, + {file = "releases-1.6.3.tar.gz", hash = "sha256:555ae4c97a671a420281c1c782e9236be25157b449fdf20b4c4b293fe93db2f1"}, +] requests = [ {file = "requests-2.27.1-py2.py3-none-any.whl", hash = "sha256:f22fa1e554c9ddfd16e6e41ac79759e17be9e492b3587efa038054674760e72d"}, {file = "requests-2.27.1.tar.gz", hash = "sha256:68d7c56fd5a8999887728ef304a6d12edc7be74f1cfa47714fc8b414525c9a61"}, ] +semantic-version = [ + {file = "semantic_version-2.6.0-py3-none-any.whl", hash = "sha256:2d06ab7372034bcb8b54f2205370f4aa0643c133b7e6dbd129c5200b83ab394b"}, + {file = "semantic_version-2.6.0.tar.gz", hash = "sha256:2a4328680073e9b243667b201119772aefc5fc63ae32398d6afafff07c4f54c0"}, +] six = [ {file = "six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"}, {file = "six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926"}, diff --git a/pyproject.toml b/pyproject.toml index 6c5d3c37..4ab1af72 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,7 +43,7 @@ Sphinx = "4.5.0" GitPython = "3.1.27" sphinx-autodoc-typehints = "1.18.1" furo = "2022.4.7" - +releases = "1.6.3" [tool.taskipy.tasks] lint = "pre-commit run --all-files" |