From e28b42f9b1e085df6961d195abe6a36210d25242 Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Wed, 11 May 2022 02:39:41 +0400 Subject: Remove Discord `MissingSentinel` Replaces the access to `discord.utils._MissingSentinel` with a simple boolean flag. This has the benefit of behaving more nicely with our doc generation. Signed-off-by: Hassan Abouelela --- botcore/_bot.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/botcore/_bot.py b/botcore/_bot.py index a36dba15..e9eba5c5 100644 --- a/botcore/_bot.py +++ b/botcore/_bot.py @@ -17,8 +17,10 @@ from botcore.utils.logging import get_logger try: from async_rediscache import RedisSession + REDIS_AVAILABLE = True except ImportError: - RedisSession = discord.utils._MissingSentinel + RedisSession = None + REDIS_AVAILABLE = False log = get_logger() @@ -70,7 +72,7 @@ class BotBase(commands.Bot): self.api_client = api_client self.statsd_url = statsd_url - if redis_session and RedisSession == discord.utils._MissingSentinel: + if redis_session and not REDIS_AVAILABLE: warnings.warn("redis_session kwarg passed, but async-rediscache not installed!") elif redis_session: self.redis_session = redis_session -- cgit v1.2.3 From ed4b2fbea5c664a1950df66a534b3233efdc5c4e Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Wed, 11 May 2022 02:42:43 +0400 Subject: Restore Releases Changelog Add the releases-based changelog system back, and migrate the old changelog entries. Signed-off-by: Hassan Abouelela --- .github/workflows/docs.yaml | 2 +- README.md | 4 +- docs/README.md | 4 +- docs/_static/changelog.css | 11 ++++ docs/_static/changelog.js | 41 +++++++++++++++ docs/changelog.rst | 124 ++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 20 +++++-- docs/index.rst | 5 +- docs/utils.py | 50 +++++++++++++++++- poetry.lock | 49 +++++++++++++---- pyproject.toml | 2 +- 11 files changed, 289 insertions(+), 23 deletions(-) create mode 100644 docs/_static/changelog.css create mode 100644 docs/_static/changelog.js create mode 100644 docs/changelog.rst 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 diff --git a/README.md b/README.md index c6f83a08..427ab10b 100644 --- a/README.md +++ b/README.md @@ -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 `: + + - 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 `: + + - 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 `: + + - 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 + changelog Extras @@ -25,4 +26,4 @@ Extras * :ref:`genindex` * :ref:`search` * :repo-file:`Information ` -* :repo-file:`Changelog ` +* :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 ` + 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 `", + 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" @@ -768,6 +767,18 @@ packaging = ">=20.4" 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" @@ -786,6 +797,14 @@ urllib3 = ">=1.21.1,<1.27" 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" @@ -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" -- cgit v1.2.3 From 4c9cad2552ebeb96f747467017ef3155595a9d1c Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Wed, 11 May 2022 04:08:42 +0400 Subject: Add Sphinx-MultiVersion Adds the sphinx-multiversion package to be used for generating docs for all versions of the project, not just the latest. This includes all the necessary configuration to make it work cleanly. Signed-off-by: Hassan Abouelela --- docs/README.md | 25 ++++++++++-- docs/_templates/base.html | 12 ++++++ docs/_templates/sidebar/navigation.html | 46 ++++++++++++++++++++++ docs/conf.py | 46 +++++++++++++++++++--- docs/pages/index_redirect.html | 19 +++++++++ docs/pages/versions.html | 23 +++++++++++ docs/utils.py | 69 +++++++++++++++++++++++++++++---- poetry.lock | 17 +++++++- pyproject.toml | 7 ++-- 9 files changed, 241 insertions(+), 23 deletions(-) create mode 100644 docs/_templates/base.html create mode 100644 docs/_templates/sidebar/navigation.html create mode 100644 docs/pages/index_redirect.html create mode 100644 docs/pages/versions.html diff --git a/docs/README.md b/docs/README.md index 2146ce5b..16c9e8cc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,6 +3,8 @@ Meta information about this project's documentation. Table of contents: - [Building the docs](#Building) +- [Docs Layout](#Layout) +- [Building all versions](#Versions) - [Writing docstrings](#Docstrings) - [Writing a changelog](#Changelog) @@ -15,11 +17,26 @@ poetry run task docs The output will be in the [`/docs/build`](.) directory. -Additionally, there are two helper tasks: `apidoc` and `builddoc`. -`apidoc` is responsible for calling autodoc and generating docs from docstrings. -`builddoc` generates the HTML site, and should be called after apidoc. -Neither of these two tasks needs to be manually called, as the `docs` task calls both. +## Versions +The project supports building all different versions at once using [sphinx-multiversion][multiversion] +after version `v7.1.0`. You can run the following command to achieve that: + +```shell +poetry run sphinx_multiversion -v docs docs/build -n -j auto -n +``` + +This will build all tags, as well as the main branch. To build branches besides the main one +(such as the one you are currently working on), set the `BUILD_DOCS_FOR_HEAD` environment variable +to True. + +When using multi-version, keep the following in mind: +1. This command will not fail on warnings, unlike the docs task. Make sure that passes first + before using this one. +2. Make sure to clear the build directory before running this script to avoid conflicts. + + +[multiversion]: https://holzhaus.github.io/sphinx-multiversion/master/index.html ## Docstrings diff --git a/docs/_templates/base.html b/docs/_templates/base.html new file mode 100644 index 00000000..541dbd0b --- /dev/null +++ b/docs/_templates/base.html @@ -0,0 +1,12 @@ +{% extends "furo/base.html" %} + +{# Make sure the project name uses the correct version #} +{% if versions %} + {% if current_version == latest_version %} + {% set docstitle = "Latest (" + current_version.version + ")" %} + {% else %} + {% set docstitle = current_version.name %} + {% endif %} + + {% set docstitle = project + " " + docstitle %} +{% endif %} diff --git a/docs/_templates/sidebar/navigation.html b/docs/_templates/sidebar/navigation.html new file mode 100644 index 00000000..02239887 --- /dev/null +++ b/docs/_templates/sidebar/navigation.html @@ -0,0 +1,46 @@ + diff --git a/docs/conf.py b/docs/conf.py index 1cea4026..12431235 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,10 +3,10 @@ import functools import os.path +import shutil import sys from pathlib import Path -import git import releases import tomli from sphinx.application import Sphinx @@ -22,10 +22,9 @@ project = "Bot Core" copyright = "2021, Python Discord" author = "Python Discord" -PROJECT_ROOT = Path(__file__).parent.parent REPO_LINK = "https://github.com/python-discord/bot-core" -SOURCE_FILE_LINK = f"{REPO_LINK}/blob/{git.Repo(PROJECT_ROOT).commit().hexsha}" +PROJECT_ROOT = Path(__file__).parent.parent sys.path.insert(0, str(PROJECT_ROOT.absolute())) # The full version, including alpha/beta/rc tags @@ -50,10 +49,11 @@ extensions = [ "releases", "sphinx.ext.linkcode", "sphinx.ext.githubpages", + "sphinx_multiversion", ] # Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +templates_path = ["_templates", "pages"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -78,6 +78,13 @@ html_theme_options = { # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] + +# Html files under pages/ are rendered separately and added to the final build +html_additional_pages = { + file.removesuffix(".html"): file + for file in utils.get_recursive_file_uris(Path("pages"), "*.html") +} + html_title = f"{project} v{version}" html_short_title = project @@ -88,7 +95,7 @@ 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() +utils.build_api_doc() def skip(*args) -> bool: @@ -103,9 +110,26 @@ def skip(*args) -> bool: return would_skip +def post_build(_: Sphinx, exception: Exception) -> None: + """Clean up and process files after the build has finished.""" + if exception: + # Don't accidentally supress exceptions + raise exception from None + + build_folder = PROJECT_ROOT / "docs" / "build" + main_build = build_folder / "main" + + if main_build.exists() and not (build_folder / "index.html").exists(): + # We don't have an index in the root folder, add a redirect + shutil.copy((main_build / "index_redirect.html"), (build_folder / "index.html")) + shutil.copytree((main_build / "_static"), (build_folder / "_static"), dirs_exist_ok=True) + (build_folder / ".nojekyll").touch(exist_ok=True) + + def setup(app: Sphinx) -> None: """Add extra hook-based autodoc configuration.""" app.connect("autodoc-skip-member", skip) + app.connect("build-finished", post_build) app.add_role("literal-url", utils.emphasized_url) # Add a `breaking` role to the changelog @@ -154,9 +178,19 @@ intersphinx_mapping = { # -- Options for the linkcode extension -------------------------------------- -linkcode_resolve = functools.partial(utils.linkcode_resolve, SOURCE_FILE_LINK) +linkcode_resolve = functools.partial(utils.linkcode_resolve, REPO_LINK) # -- Options for releases extension ------------------------------------------ releases_github_path = REPO_LINK.removeprefix("https://github.com/") releases_release_uri = f"{REPO_LINK}/releases/tag/v%s" + + +# -- Options for the multiversion extension ---------------------------------- +# Only include local refs, filter out older versions, and don't build branches other than main +# unless `BUILD_DOCS_FOR_HEAD` env variable is True. +smv_remote_whitelist = None +smv_latest_version = "main" +if os.getenv("BUILD_DOCS_FOR_HEAD", "False").lower() == "false": + smv_branch_whitelist = "main" +smv_tag_whitelist = r"v(?!([0-6]\.)|(7\.[0-1]\.0))" # Don't include any versions prior to v7.1.1 diff --git a/docs/pages/index_redirect.html b/docs/pages/index_redirect.html new file mode 100644 index 00000000..3745c62c --- /dev/null +++ b/docs/pages/index_redirect.html @@ -0,0 +1,19 @@ +{% extends "base.html" %} +{% set pagename = master_doc %} + +{# Redirect users to the actual docs page #} +{% block site_meta %} + {# Make sure this is loaded as early as possible #} + + {{ super() }} +{% endblock %} + +{# Show some text in-case the redirection fails #} +{% block body %} + {{ super() }} + +{% endblock %} diff --git a/docs/pages/versions.html b/docs/pages/versions.html new file mode 100644 index 00000000..f4564dbf --- /dev/null +++ b/docs/pages/versions.html @@ -0,0 +1,23 @@ +{% extends "page.html" %} +{% set title = "Versions" %} + +{% block content -%} + {% if versions %} +

Versions

+
+
Documentation is available for the following versions:
+
    + {# List all avaialble versions #} + {% for version in versions | reverse %} +
  • + {{ version.name }} + {{ "(current)" if version == current_version }} + {{ "- latest" if version == latest_version }} +
  • + {% endfor %} +
+
+ {% else %} +

No version information available!

+ {% endif %} +{%- endblock %} diff --git a/docs/utils.py b/docs/utils.py index aaa656c3..bb8074ba 100644 --- a/docs/utils.py +++ b/docs/utils.py @@ -1,19 +1,31 @@ """Utilities used in generating docs.""" import ast -import importlib +import importlib.util import inspect +import os +import subprocess import typing from pathlib import Path import docutils.nodes import docutils.parsers.rst.states +import git import releases +import sphinx.util.logging -PROJECT_ROOT = Path(__file__).parent.parent +logger = sphinx.util.logging.getLogger(__name__) -def linkcode_resolve(source_url: str, domain: str, info: dict[str, str]) -> typing.Optional[str]: +def get_build_root() -> Path: + """Get the project root folder for the current build.""" + root = Path.cwd() + if root.name == "docs": + root = root.parent + return root + + +def linkcode_resolve(repo_link: str, domain: str, info: dict[str, str]) -> typing.Optional[str]: """ Function called by linkcode to get the URL for a given resource. @@ -25,7 +37,25 @@ def linkcode_resolve(source_url: str, domain: str, info: dict[str, str]) -> typi symbol_name = info["fullname"] - module = importlib.import_module(info["module"]) + build_root = get_build_root() + + # Import the package to find files + origin = build_root / info["module"].replace(".", "/") + search_locations = [] + + if origin.is_dir(): + search_locations.append(origin.absolute().as_posix()) + origin = origin / "__init__.py" + else: + origin = Path(origin.absolute().as_posix() + ".py") + if not origin.exists(): + raise Exception(f"Could not find `{info['module']}` as a package or file.") + + # We can't use a normal import (importlib.import_module), because the module can conflict with another copy + # in multiversion builds. We load the module from the file location instead + spec = importlib.util.spec_from_file_location(info["module"], origin, submodule_search_locations=search_locations) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) symbol = [module] for name in symbol_name.split("."): @@ -62,9 +92,15 @@ def linkcode_resolve(source_url: str, domain: str, info: dict[str, str]) -> typi start += offset end += offset - file = Path(inspect.getfile(module)).relative_to(PROJECT_ROOT).as_posix() + file = Path(inspect.getfile(module)).relative_to(build_root).as_posix() + + try: + sha = git.Repo(build_root).commit().hexsha + except git.InvalidGitRepositoryError: + # We are building a historical version, no git data available + sha = build_root.name - url = f"{source_url}/{file}#L{start}" + url = f"{repo_link}/blob/{sha}/{file}#L{start}" if end != start: url += f"-L{end}" @@ -75,7 +111,7 @@ def cleanup() -> None: """Remove unneeded autogenerated doc files, and clean up others.""" included = __get_included() - for file in (PROJECT_ROOT / "docs" / "output").iterdir(): + for file in (get_build_root() / "docs" / "output").iterdir(): if file.name in ("botcore.rst", "botcore.exts.rst", "botcore.utils.rst") and file.name in included: content = file.read_text(encoding="utf-8").splitlines(keepends=True) @@ -96,7 +132,6 @@ def cleanup() -> None: else: # These are files that have not been explicitly included in the docs via __all__ - print("Deleted file", file.name) file.unlink() continue @@ -105,6 +140,24 @@ def cleanup() -> None: file.write_text(content, encoding="utf-8") +def build_api_doc() -> None: + """Generate auto-module directives using apidoc.""" + cmd = os.getenv("APIDOC_COMMAND") or "sphinx-apidoc -o docs/output botcore -feM" + cmd = cmd.split() + + build_root = get_build_root() + output_folder = build_root / cmd[cmd.index("-o") + 1] + + if output_folder.exists(): + logger.info(f"Skipping api-doc for {output_folder.as_posix()} as it already exists.") + return + + result = subprocess.run(cmd, cwd=build_root, stdout=subprocess.PIPE, check=True, env=os.environ) + logger.debug("api-doc Output:\n" + result.stdout.decode(encoding="utf-8") + "\n") + + cleanup() + + def __get_included() -> set[str]: """Get a list of files that should be included in the final build.""" diff --git a/poetry.lock b/poetry.lock index af24501a..18c91773 100644 --- a/poetry.lock +++ b/poetry.lock @@ -892,6 +892,17 @@ Sphinx = ">=4.5" testing = ["covdefaults (>=2.2)", "coverage (>=6.3)", "diff-cover (>=6.4)", "nptyping (>=2)", "pytest (>=7.1)", "pytest-cov (>=3)", "sphobjinv (>=2)", "typing-extensions (>=4.1)"] type_comments = ["typed-ast (>=1.5.2)"] +[[package]] +name = "sphinx-multiversion" +version = "0.2.4" +description = "Add support for multiple versions to sphinx" +category = "dev" +optional = false +python-versions = "*" + +[package.dependencies] +sphinx = ">=2.1" + [[package]] name = "sphinxcontrib-applehelp" version = "1.0.2" @@ -1078,7 +1089,7 @@ async-rediscache = ["async-rediscache"] [metadata] lock-version = "1.1" python-versions = "3.9.*" -content-hash = "b4b7d5cf3933b4237051c02050f3dadefa58ad39e5cebc7434f097b7315ea179" +content-hash = "c59b21365534625a127a8bfaffd41a704714c3241817f4d71ad86b68602cf930" [metadata.files] aiohttp = [ @@ -1771,6 +1782,10 @@ sphinx-autodoc-typehints = [ {file = "sphinx_autodoc_typehints-1.18.1-py3-none-any.whl", hash = "sha256:f8f5bb7c13a9a71537dc2be2eb3b9e28a9711e2454df63587005eacf6fbac453"}, {file = "sphinx_autodoc_typehints-1.18.1.tar.gz", hash = "sha256:07631c5f0c6641e5ba27143494aefc657e029bed3982138d659250e617f6f929"}, ] +sphinx-multiversion = [ + {file = "sphinx-multiversion-0.2.4.tar.gz", hash = "sha256:5cd1ca9ecb5eed63cb8d6ce5e9c438ca13af4fa98e7eb6f376be541dd4990bcb"}, + {file = "sphinx_multiversion-0.2.4-py3-none-any.whl", hash = "sha256:dec29f2a5890ad68157a790112edc0eb63140e70f9df0a363743c6258fbeb478"}, +] sphinxcontrib-applehelp = [ {file = "sphinxcontrib-applehelp-1.0.2.tar.gz", hash = "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"}, {file = "sphinxcontrib_applehelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a"}, diff --git a/pyproject.toml b/pyproject.toml index 4ab1af72..4290417f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "bot-core" -version = "7.1.0" +version = "7.1.1" description = "Bot-Core provides the core functionality and utilities for the bots of the Python Discord community." authors = ["Python Discord "] license = "MIT" @@ -44,13 +44,12 @@ GitPython = "3.1.27" sphinx-autodoc-typehints = "1.18.1" furo = "2022.4.7" releases = "1.6.3" +sphinx-multiversion = "0.2.4" [tool.taskipy.tasks] lint = "pre-commit run --all-files" precommit = "pre-commit install" -apidoc = "sphinx-apidoc -o docs/output botcore -feM" -builddoc = "sphinx-build -nW -j auto -b html docs docs/build" -docs = "task apidoc && task builddoc" +docs = "sphinx-build -nW -j auto -b html docs docs/build" test = "pytest -n 8 --ff" retest = "pytest -n 8 --lf" -- cgit v1.2.3 From 8f2067b0f2f9cd6001a9565f8da4590f5b414f1e Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 16:27:22 +0400 Subject: Document The Docs Folder Add a brief explanation about each item in the docs folder, to help contributors navigate and understand what each part does. Signed-off-by: Hassan Abouelela --- docs/README.md | 19 +++++++++++++++++++ docs/changelog.rst | 1 + 2 files changed, 20 insertions(+) diff --git a/docs/README.md b/docs/README.md index 16c9e8cc..89124d5e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,25 @@ poetry run task docs The output will be in the [`/docs/build`](.) directory. +## Layout +The docs folder has a few moving components, here's a brief description of each: + +- `_static`: This folder includes extra resources that are copied blindly by sphinx into the result + making it perfect for resources such as custom CSS or JS. +- `_templates` & `pages`: Both are considered HTML templates, and passed to Sphinx as `templates_path`. + The difference between them is that `_templates` is only used to provide templates and overrides that + are used by other pages, while `pages` are full-blown independent pages that will be included in the + result. Files in `pages` are passed to Sphinx as `html_additional_pages`, and will maintain the same + structure as the folder. That is to say, a file such as `pages/a/b.html` will create `https://bot-core/a/b.html`. +- `changelog.rst`: This contains a list of all the project's changes. Please refer to [Changelog](#Changelog) + below for more info. +- `index.rst`: The main content for the project's homepage. +- `conf.py`: Configuration for Sphinx. This includes things such as the project name, version, + plugins and their configuration. +- `utils.py`: Helpful function used by `conf.py` to properly create the docs. +- `netliy_build.py`: Script which downloads the build output in netlify. Refer to [Static Netlify Build](#static-builds) + + ## Versions The project supports building all different versions at once using [sphinx-multiversion][multiversion] after version `v7.1.0`. You can run the following command to achieve that: diff --git a/docs/changelog.rst b/docs/changelog.rst index 3cee3a7a..a4c60ef3 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -4,6 +4,7 @@ Changelog ========= +- :support:`79` Add `sphinx-multiversion `_ to make available older doc versions. - :support:`79` Restore on-site changelog. -- cgit v1.2.3 From b2c846203a968519a7b764c58abb5244c04b6f75 Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 22:39:47 +0400 Subject: Delete CHANGELOG.md Deleted CHANGELOG.md in favor of the changelog in the docs. Signed-off-by: Hassan Abouelela --- CHANGELOG.md | 88 ------------------------------------------------------------ 1 file changed, 88 deletions(-) delete mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index e6c217f4..00000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,88 +0,0 @@ -# Changelog - -## 7.1.0 24th May 2022 -- Feature: Bump Discord.py to [`4cbe8f5`](https://github.com/Rapptz/discord.py/tree/4cbe8f58e16f6a76371ce45a69e0832130d6d24f) - - This fixes a bug with permission resolution when dealing with timed out members. - -## 7.0.0 10th May 2022 -- Fix: Capture all characters up to a whitespace in the Discord Invite regex. -- Breaking: Discord invite regex no longer returns a URL safe result, refer to documentation for safely handling it. - -## 6.4.0 26th April 2022 -- Feature: Bump discord.py to `[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. - -## 6.3.2 25th April 2022 -- Fix: Actually use `statsd_url` when it gets passed to `BotBase`. - -## 6.3.1 21st April 2022 -- Fix: Correct version number in pyproject.toml - -## 6.3.0 21st April 2022 -- Feature: Don't load modules starting with `_` - -## 6.2.0 21st April 2022 -- Feature: Load each cog in it's own task to avoid a single cog crashing entire load process. - -## 6.1.0 20th April 2022 -- Feature: Add `unqualify` to the `botcore.utils` namespace for use in bots that manipulate extensions - -## 6.0.0 19th April 2022 -- Breaking: Bump discord.py to [987235d5649e7c2b1a927637bab6547244ecb2cf](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 - -## 5.0.4 18th April 2022 -- Feature: Allow passing an `api_client` to `BotBase`.`__init__` to specify the `botcore.site_api.APIClient` instance to use. - -## 5.0.3 18th April 2022 -- Fix: Reconnect to redis session on setup if it is closed. - -## 5.0.2 5th April 2022 -- Fix: Create a dummy `AsyncstatsdClient` before connecting to real url, in case a connection cannot be made on init. -- Fix: Move the creation of the `asyncio.Event`, `BotBase._guild_available` to within the setup hook, to avoid a deprecation notice. - -## 5.0.1 2nd April 2022 -- Fix: Move creation of BotBase's `aiohttp.AsyncResolver` to the async setup hook, to avoid deprecation notice - -## 5.0.0 2nd April 2022 -- Breaking: Remove public extensions util -- Feature: Add `BotBase`, a `discord.ext.commands.Bot` sub-class, which abstracts a lot of logic shared between our bots -- Feature: Add async statsd client -- Dependencies: Bump Discord.py to latest alpha commit - -## 4.0.0 14th March 2022 -- Breaking: Migrate back to Discord.py 2.0 - -## 3.0.1 5th March 2022 -- Fix: Setup log tracing when `botcore.utils.logging` is imported so that it can be used within botcore functions. - -## 3.0.0 3rd March 2022 - - Breaking: Move `apply_monkey_patches()` directly to `botcore.utils` namespace - -## 2.1.0 24th February 2022 - - Feature: Port the Site API wrapper from the bot repo. - -## 2.0.0 22nd February 2022 -- Breaking: Moved regex to `botcore.utils` namespace -- Feature: Migrate from discord.py 2.0a0 to disnake. -- Feature: Add common monkey patches. -- Feature: Port many common utilities from our bots - - caching - - channel - - extensions - - loggers - - members - - scheduling -- Support: Added intersphinx to docs. - -## 1.2.0 9th January 2022 -- Feature: Add code block detection regex. - -## 1.1.0 2nd December 2021 -- Support: Add autogenerated docs. -- Feature: Add a regex utility. - - -## 1.0.0 17th November 2021 -- Support: Add the core package, poetry, and linting CI. -- cgit v1.2.3 From 8bf56038efdbedca7e01316cc3a295b8c38986d8 Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 23:07:05 +0400 Subject: Declare Releases As Parallel-Read Safe Signed-off-by: Hassan Abouelela --- docs/conf.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 12431235..c4f24035 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -186,6 +186,16 @@ releases_github_path = REPO_LINK.removeprefix("https://github.com/") releases_release_uri = f"{REPO_LINK}/releases/tag/v%s" +def _releases_setup(app: Sphinx) -> dict: + """Wrap the default setup of releases to declare it as parallel-read safe.""" + _original_releases_setup(app) + return {"parallel_read_safe": True} + + +_original_releases_setup = releases.setup +releases.setup = _releases_setup + + # -- Options for the multiversion extension ---------------------------------- # Only include local refs, filter out older versions, and don't build branches other than main # unless `BUILD_DOCS_FOR_HEAD` env variable is True. -- cgit v1.2.3 From 2803e0a372e7dc745ab719485d4d6f42bbdae282 Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 23:25:06 +0400 Subject: Only Build Current Branch When Option Enabled Changes the behavior of `BUILD_DOCS_FOR_HEAD` to add only the current branch to the build whitelist, instead of all branches. Signed-off-by: Hassan Abouelela --- docs/conf.py | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c4f24035..386303dd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,10 +7,14 @@ import shutil import sys from pathlib import Path +import git import releases +import sphinx.util.logging import tomli from sphinx.application import Sphinx +logger = sphinx.util.logging.getLogger(__name__) + # Handle the path not being set correctly in actions. sys.path.insert(0, os.path.abspath('..')) @@ -201,6 +205,14 @@ releases.setup = _releases_setup # unless `BUILD_DOCS_FOR_HEAD` env variable is True. smv_remote_whitelist = None smv_latest_version = "main" -if os.getenv("BUILD_DOCS_FOR_HEAD", "False").lower() == "false": - smv_branch_whitelist = "main" + +smv_branch_whitelist = "main" +if os.getenv("BUILD_DOCS_FOR_HEAD", "False").lower() == "true": + try: + branch = git.Repo(PROJECT_ROOT).active_branch.name + logger.info(f"Adding branch {branch} to build whitelist") + smv_branch_whitelist = f"main|{branch}" + except git.InvalidGitRepositoryError: + pass + smv_tag_whitelist = r"v(?!([0-6]\.)|(7\.[0-1]\.0))" # Don't include any versions prior to v7.1.1 -- cgit v1.2.3 From 41f6b02a7d6bd83a6636d83c0bcbaea6988cd6bb Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 23:25:33 +0400 Subject: Update Docs CI For Multiversion Signed-off-by: Hassan Abouelela --- .github/workflows/docs.yaml | 39 ++++++++++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 79a96ea5..82344abc 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -13,8 +13,9 @@ concurrency: jobs: - build-deploy: - name: Build & Deploy Docs + latest-build: + # We only need to verify that the docs build with no warnings here + name: Build Latest Docs Version runs-on: ubuntu-latest steps: @@ -31,12 +32,40 @@ jobs: # https://github.com/bitprophet/releases/pull/82 - run: pip install six - - name: Generate AutoDoc References - run: sphinx-apidoc -o docs/output botcore -feM - - name: Generate HTML Site run: sphinx-build -nW -j auto -b html docs docs/build + - name: Upload Build Artifact + uses: actions/upload-artifact@v2 + with: + name: docs-latest + path: docs/build/* + + build-deploy: + name: Build & Deploy Docs + runs-on: ubuntu-latest + needs: + - latest-build + + steps: + - uses: actions/checkout@v2 + + - name: Install Python Dependencies + uses: HassanAbouelela/actions/setup-python@setup-python_v1.1.0 + with: + dev: true + python_version: 3.9 + install_args: "--extras async-rediscache" + + # Undeclared dependency for `releases`... whoops + # https://github.com/bitprophet/releases/pull/82 + - run: pip install six + + - name: Build All Doc Versions + run: sphinx-multiversion docs docs/build -n -j auto + env: + BUILD_DOCS_FOR_HEAD: True + - name: Upload Build Artifact uses: actions/upload-artifact@v2 with: -- cgit v1.2.3 From 4c32cca1054a3ffe34b90dd25185cd2ad7ab068f Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 23:36:59 +0400 Subject: Check Out The Entire Repository For Multiversion Signed-off-by: Hassan Abouelela --- .github/workflows/docs.yaml | 4 +++- docs/conf.py | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 82344abc..7bc0102d 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -49,6 +49,8 @@ jobs: steps: - uses: actions/checkout@v2 + with: + fetch-depth: 0 # We need to check out the entire repository to find all tags - name: Install Python Dependencies uses: HassanAbouelela/actions/setup-python@setup-python_v1.1.0 @@ -64,7 +66,7 @@ jobs: - name: Build All Doc Versions run: sphinx-multiversion docs docs/build -n -j auto env: - BUILD_DOCS_FOR_HEAD: True + BUILD_DOCS_FOR_HEAD: ${{ github.event_name == 'pull_request' }} - name: Upload Build Artifact uses: actions/upload-artifact@v2 diff --git a/docs/conf.py b/docs/conf.py index 386303dd..e4293486 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -210,7 +210,7 @@ smv_branch_whitelist = "main" if os.getenv("BUILD_DOCS_FOR_HEAD", "False").lower() == "true": try: branch = git.Repo(PROJECT_ROOT).active_branch.name - logger.info(f"Adding branch {branch} to build whitelist") + logger.info(f"Adding branch {branch} to build whitelist.") smv_branch_whitelist = f"main|{branch}" except git.InvalidGitRepositoryError: pass -- cgit v1.2.3 From f5c4f7b6f3b10fafd5613a7bec469235443dec24 Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 23:48:31 +0400 Subject: Pass Branch Name To Docs In CI Signed-off-by: Hassan Abouelela --- .github/workflows/docs.yaml | 1 + docs/conf.py | 11 +++++++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 7bc0102d..8797d8f5 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -67,6 +67,7 @@ jobs: run: sphinx-multiversion docs docs/build -n -j auto env: BUILD_DOCS_FOR_HEAD: ${{ github.event_name == 'pull_request' }} + BRANCH_NAME: ${{ github.head_ref }} - name: Upload Build Artifact uses: actions/upload-artifact@v2 diff --git a/docs/conf.py b/docs/conf.py index e4293486..aa9580fe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -208,11 +208,14 @@ smv_latest_version = "main" smv_branch_whitelist = "main" if os.getenv("BUILD_DOCS_FOR_HEAD", "False").lower() == "true": - try: - branch = git.Repo(PROJECT_ROOT).active_branch.name + if not (branch := os.getenv("BRANCH_NAME")): + try: + branch = git.Repo(PROJECT_ROOT).active_branch.name + except git.InvalidGitRepositoryError: + pass + + if branch: logger.info(f"Adding branch {branch} to build whitelist.") smv_branch_whitelist = f"main|{branch}" - except git.InvalidGitRepositoryError: - pass smv_tag_whitelist = r"v(?!([0-6]\.)|(7\.[0-1]\.0))" # Don't include any versions prior to v7.1.1 -- cgit v1.2.3 From 9934436aa2214082896e99bdf2174642a06c5b61 Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 23:50:14 +0400 Subject: Include `origin` In Allowed Docs Versions Signed-off-by: Hassan Abouelela --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index aa9580fe..9aaa8eff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -201,9 +201,9 @@ releases.setup = _releases_setup # -- Options for the multiversion extension ---------------------------------- -# Only include local refs, filter out older versions, and don't build branches other than main +# Filter out older versions, and don't build branches other than main # unless `BUILD_DOCS_FOR_HEAD` env variable is True. -smv_remote_whitelist = None +smv_remote_whitelist = "origin" smv_latest_version = "main" smv_branch_whitelist = "main" -- cgit v1.2.3 From 679f72ccba3e7a12a74f519d715eaf3df913e7b4 Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Mon, 30 May 2022 20:45:11 +0400 Subject: Fix Entry In Changelog Signed-off-by: Hassan Abouelela --- docs/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index a4c60ef3..62e97fbb 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -55,7 +55,7 @@ Changelog - :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 + Feature 63 Needs to be explicitly included above 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. -- cgit v1.2.3 From 7c8c4dbe6bb6e2f5a82afb4dd6302f29ae345a3b Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Mon, 30 May 2022 21:01:44 +0400 Subject: Speed Up Docs CI Removes unnecessary `depends-on` to speed up builds. Signed-off-by: Hassan Abouelela --- .github/workflows/docs.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 8797d8f5..5254d524 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -44,8 +44,6 @@ jobs: build-deploy: name: Build & Deploy Docs runs-on: ubuntu-latest - needs: - - latest-build steps: - uses: actions/checkout@v2 -- cgit v1.2.3 From 5a4883bbd078c0cdbea6aed3e6aefbb4b136a6ea Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Mon, 30 May 2022 22:02:38 +0400 Subject: Fix Bullet Points In Changelog Co-authored-by: Chris Lovering Signed-off-by: Hassan Abouelela --- docs/changelog.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 62e97fbb..e666a266 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -11,7 +11,7 @@ Changelog - :release:`7.1.0 <24th May 2022>` - :feature:`78` Bump Discord.py to :literal-url:`4cbe8f5 `: - - This fixes a bug with permission resolution when dealing with timed out members. + - This fixes a bug with permission resolution when dealing with timed out members. - :release:`7.0.0 <10th May 2022>` @@ -22,7 +22,7 @@ Changelog - :release:`6.4.0 <26th April 2022>` - :feature:`72` Bump discord.py to :literal-url:`5a06fa5 `: - - 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. + - 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>` @@ -48,8 +48,8 @@ Changelog - :release:`6.0.0 <19th April 2022>` - :breaking:`64` Bump discord.py to :literal-url:`987235d `: - - This reverts a change to help command behaviour that broke our custom pagination - - This also adds basic forum channel support to discord.py + - 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 @@ -103,12 +103,12 @@ Changelog - :feature:`32` Add common monkey patches. - :feature:`29` Port many common utilities from our bots: - - caching - - channel - - extensions - - loggers - - members - - scheduling + - caching + - channel + - extensions + - loggers + - members + - scheduling - :support:`2` Added intersphinx to docs. -- cgit v1.2.3