From d8a51ea0379cce18859ea50d40dbc29a9e73e058 Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Mon, 25 Nov 2024 21:22:28 -0800 Subject: [PATCH] feat: Add insiders documentation features. (#48) --- .readthedocs.yml | 2 + README.md | 4 - docs/_static/css/theme_overrides.css | 7 +- .../python/readthedocs/children.html.jinja | 6 +- .../python/readthedocs/class.html.jinja | 50 +++++++ mkdocs.yml | 46 +++--- pyproject.toml | 16 ++- scripts/install_insiders_packages.py | 133 ++++++++++++++++++ 8 files changed, 232 insertions(+), 32 deletions(-) create mode 100644 docs/_templates/mkdocstrings/python/readthedocs/class.html.jinja create mode 100644 scripts/install_insiders_packages.py diff --git a/.readthedocs.yml b/.readthedocs.yml index 1494771..547f238 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -5,6 +5,8 @@ build: tools: python: '3.11' # This needs to stay in sync with the tox config in pyproject.toml and any CI scripts nodejs: '20' # This needs to stay in sync with any CI scripts + jobs: + post_install: [python scripts/install_insiders_packages.py] python: install: - requirements: docs/requirements.txt diff --git a/README.md b/README.md index c76d1e2..7e5565f 100644 --- a/README.md +++ b/README.md @@ -71,10 +71,6 @@ pip install tekhsi -
- -
- ## Documentation See the full documentation at diff --git a/docs/_static/css/theme_overrides.css b/docs/_static/css/theme_overrides.css index cdd1206..fc017f6 100644 --- a/docs/_static/css/theme_overrides.css +++ b/docs/_static/css/theme_overrides.css @@ -131,8 +131,7 @@ a.autorefs:hover, a.autorefs:hover code, .rst-content .admonition a.autorefs:hov color: #d600d6 !important; } -/* Hide all ToC entries for auto-generated command parts. */ -li:has(> a[href^="gen_"]), -li:has(> a[href*="/gen_"]) { - display: none; +/* Remove the mermaidTooltip */ +.mermaidTooltip { + display: none !important; } diff --git a/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja b/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja index 324e181..11d8619 100644 --- a/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja +++ b/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja @@ -16,13 +16,11 @@ Context: {%- for item in item_list %} {%- if item.docstring %} - {%- filter stash_crossref(length=item.canonical_path|length) -%} - + {{ item.name }} - + - {%- endfilter -%} {{ item.docstring.parsed[0].value.split("\n")[0]|convert_markdown(heading_level, html_id) }} {%- endif %} diff --git a/docs/_templates/mkdocstrings/python/readthedocs/class.html.jinja b/docs/_templates/mkdocstrings/python/readthedocs/class.html.jinja new file mode 100644 index 0000000..42b2c31 --- /dev/null +++ b/docs/_templates/mkdocstrings/python/readthedocs/class.html.jinja @@ -0,0 +1,50 @@ +{# TODO: Drop Python 3.8: remove this file after updating to newer versions of mkdocstrings-python #} +{% extends "_base/class.html.jinja" %} + {% block inheritance_diagram %} + {#- Inheritance diagram block. + + This block renders the inheritance diagram for the class, + using Mermaid syntax and a bit of JavaScript to make the nodes clickable, + linking to the corresponding class documentation. + -#} + {% if config.show_inheritance_diagram and class.bases %} + {% macro edges(class) %} + {% for base in class.resolved_bases %} + {{ base.path }} --> {{ class.path }} + {{ edges(base) }} + {% endfor %} + {% endmacro %} +
+ + {% for base in class.mro() %} + + {% endfor %} +
+
+ flowchart LR + {{ class.path }}[{{ class.name }}] + {% for base in class.mro() %} + {{ base.path }}[{{ base.name }}] + {% endfor %} + + {{ edges(class) | safe }} + + click {{ class.path }} href "" "{{ class.path }}" + {% for base in class.mro() %} + click {{ base.path }} href "" "{{ base.path }}" + {% endfor %} +
+ + + {% endif %} + {% endblock inheritance_diagram %} diff --git a/mkdocs.yml b/mkdocs.yml index 6d52749..860886d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -59,7 +59,6 @@ markdown_extensions: - def_list - pymdownx.snippets: check_paths: true - dedent_subsections: true - pymdownx.highlight: use_pygments: true pygments_style: default @@ -90,7 +89,8 @@ plugins: use_default: true inline_refs: none markdown_links: true - - mermaid2 + - mermaid2: + javascript: https://unpkg.com/mermaid@11.3.0/dist/mermaid.min.js - mkdocstrings: # additional customization takes place in docs/generate_api_pages.py enable_inventory: true custom_templates: docs/_templates/mkdocstrings @@ -98,28 +98,36 @@ plugins: python: # see https://mkdocstrings.github.io/python/usage/ paths: [src] options: - docstring_options: - ignore_init_summary: true - trim_doctest_flags: true - merge_init_into_class: true - members_order: alphabetical - show_inheritance_diagram: true - inherited_members: true + # General options + show_inheritance_diagram: true # INSIDERS FEATURE show_source: false # a link is included at the top of each page - docstring_section_style: list - filters: ['!^_', ^__init__] - summary: true - show_signature_annotations: true - separate_signature: true - line_length: 100 - signature_crossrefs: true - show_labels: true + # Headings options heading_level: 1 show_root_heading: true show_root_full_path: false show_category_heading: false show_symbol_type_heading: true show_symbol_type_toc: false + # Members options + inherited_members: true + members_order: alphabetical + filters: ['!^_', ^__init__] + summary: false # Currently implemented with custom templates + show_labels: true + # Docstrings options + docstring_options: + ignore_init_summary: true + trim_doctest_flags: true + docstring_section_style: list + merge_init_into_class: true + relative_crossrefs: true # INSIDERS FEATURE + scoped_crossrefs: true # INSIDERS FEATURE + # Signature options + line_length: 100 + modernize_annotations: false # INSIDERS FEATURE (if the source code annotations format changes, update this to true) + show_signature_annotations: true + signature_crossrefs: true + separate_signature: true import: - url: https://docs.python.org/3/objects.inv domains: [std, py] @@ -154,8 +162,8 @@ plugins: strict_only: true nav: # The first entry in each section needs a hard-coded title to avoid being folded in as the section index - index.md - - Usage Guide: - - Basic usage: basic_usage.md + - The Basics: + - Basic Usage: basic_usage.md - glossary.md - CHANGELOG.md - Contributing: diff --git a/pyproject.toml b/pyproject.toml index dec29a5..02213a9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,7 +67,7 @@ typing_extensions = "^4.12.0" tzlocal = "^5.2" [tool.poetry.group.dev.dependencies] -docutils = "^0.20" # TODO: remove this when the minimum Python version is >=3.9 +docutils = "^0.20" # TODO: Drop Python 3.8: remove this when the minimum Python version is >=3.9 docutils-stubs = "^0.0.22" matplotlib = [ {python = ">=3.9", version = "^3.8"}, @@ -112,8 +112,10 @@ mkdocs-spellcheck = "^1.1.0" mkdocstrings = "^0.26.1" mkdocstrings-python = "^1.10.2" nodeenv = "^1.9.1" +packaging = "^24.2" pygments = "^2.17.2" pymdown-extensions = "^10.8.1" +requests = "^2.32.3" symspellpy = "^6.7.7" tomli = "^2.0.1" @@ -416,21 +418,33 @@ commands_pre = [testenv:docs] basepython = {env:DOC_PYTHON_VERSION} +passenv = + GITHUB_PAT deps = -rdocs/requirements.txt commands_pre = nodeenv --python-virtualenv --clean-src + python scripts/install_insiders_packages.py commands = python -c "import shutil; shutil.rmtree('.results_{envname}', ignore_errors=True)" mkdocs --verbose build --site-dir .results_{envname} [testenv:doctests] basepython = {env:DOC_PYTHON_VERSION} +passenv = + GITHUB_PAT deps = -rdocs/requirements.txt -rtests/requirements.txt commands_pre = nodeenv --python-virtualenv --clean-src + python scripts/install_insiders_packages.py commands = pytest -v -k "test_docs" --showlocals --junitxml={tox_root}/.results_{envname}/results.xml --self-contained-html --html={tox_root}/.results_{envname}/results.html + +[testenv:export-reqs] +commands = + poetry export --without-hashes --without-urls --all-extras --only=docs --output=docs/requirements.txt + poetry export --without-hashes --without-urls --all-extras --only=tests --output=tests/requirements.txt + - pre-commit run -a requirements-txt-fixer """ diff --git a/scripts/install_insiders_packages.py b/scripts/install_insiders_packages.py new file mode 100644 index 0000000..d5b1939 --- /dev/null +++ b/scripts/install_insiders_packages.py @@ -0,0 +1,133 @@ +"""Install insiders packages corresponding to currently installed versions of specified packages.""" + +import importlib.metadata +import logging +import os +import subprocess +import sys + +from typing import List + +import requests + +from packaging.version import parse as parse_version + +logging.basicConfig( + level=getattr(logging, os.getenv("LOGGING_LEVEL", "INFO")), + format="[%(asctime)s] [%(levelname)8s] %(message)s", +) +logger = logging.getLogger(__name__) + +PACKAGE_LIST = { + "mkdocstrings-python": "https://github.com/pawamoy-insiders/mkdocstrings-python", + "griffe": "https://github.com/pawamoy-insiders/griffe", +} + + +def get_github_tags(repo_url_str: str, github_token: str) -> List[str]: + """Get the tags for a GitHub repository. + + Args: + repo_url_str: The URL of the GitHub repository. + github_token: The GitHub token to use for authentication. + + Returns: + A list of tag names for the repository. + """ + # Extract the owner and repository name from the URL + parts = repo_url_str.rstrip("/").split("/") + owner, repo = parts[-2], parts[-1] + + try: + response = requests.get( + f"https://api.github.com/repos/{owner}/{repo}/tags", + headers={"Authorization": f"token {github_token}"}, + timeout=30, + ) + response.raise_for_status() # Raise an exception for HTTP errors + + tags = response.json() + return [tag["name"] for tag in tags] + + except requests.exceptions.RequestException: + logger.error("Error getting tags for %s", repo_url_str) # noqa: TRY400 + return [] + + +def get_newest_matching_tag(current_version: str, tags: List[str]) -> str: + """Find the newest tag that starts with the given current version. + + Args: + current_version: The current version of the package. + tags: A list of tag names. + + Returns: + The newest tag that starts with the current version, or an empty string if none are found. + """ + # Filter tags that start with the current version + matching_tags = [tag for tag in tags if tag.startswith(current_version)] + + # Sort matching tags as version numbers in descending order + matching_tags.sort(key=parse_version, reverse=True) + + return matching_tags[0] if matching_tags else "" + + +def install_package(package_name: str, repo_url_str: str, tag: str, github_token: str) -> None: + """Install a package from a GitHub repository using a specific tag. + + Args: + package_name: The name of the package to install. + repo_url_str: The HTTPS URL of the GitHub repository. + tag: The tag to install. + github_token: The GitHub token to use for authentication. + """ + # Insert the token into the URL for authentication + repo_url_str = repo_url_str.replace("https://", f"https://{github_token}@") + + install_url = f"{repo_url_str}.git@{tag}" + try: + logger.info("Installing %s from tag %s", package_name, tag) + subprocess.check_call( # noqa: S603 + [sys.executable, "-m", "pip", "install", f"git+{install_url}"], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + logger.info("Successfully installed %s from tag %s", package_name, tag) + except subprocess.CalledProcessError: + logger.error("Failed to install %s from tag %s", package_name, tag) # noqa: TRY400 + + +def main() -> None: + """Install insiders packages.""" + if not (github_token := os.environ.get("GITHUB_PAT")): + logger.info( + "GITHUB_PAT environment variable is not set, no insiders packages will be installed." + ) + return + for package, repo_url in PACKAGE_LIST.items(): + logger.info("Processing %s", package) + try: + version = importlib.metadata.version(package) + logger.info("%s installed version is %s", package, version) + except importlib.metadata.PackageNotFoundError: + logger.warning("%s is not installed.", package) + version = None + + if version and (package_tags := get_github_tags(repo_url, github_token)): + logger.info("Tags for %s: %s", package, package_tags) + + if newest_tag := get_newest_matching_tag(version, package_tags): + logger.info( + 'Newest matching tag for %s version %s is "%s"', + package, + version, + newest_tag, + ) + install_package(package, repo_url, newest_tag, github_token) + else: + logger.info("No matching tags found for %s with version %s", package, version) + + +if __name__ == "__main__": + main()