From 5a3b35f5ac1ea46769d53186d75d5b1165365f15 Mon Sep 17 00:00:00 2001 From: Eric Callahan Date: Fri, 26 Jan 2024 20:20:44 -0500 Subject: [PATCH] docs: add collapse_code extension from pymdown-ex This extension is used to collapse the example responses presented in the API documentation, which can be quite long. Signed-off-by: Eric Callahan --- docs/doc-requirements.txt | 1 + docs/pymdown-extras/collapse_code.py | 129 +++++++++++++++++++++++++++ docs/pymdown-extras/setup.py | 7 ++ mkdocs.yml | 5 +- 4 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 docs/pymdown-extras/collapse_code.py create mode 100644 docs/pymdown-extras/setup.py diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt index eb2937f..b653d97 100644 --- a/docs/doc-requirements.txt +++ b/docs/doc-requirements.txt @@ -1,2 +1,3 @@ mkdocs-material==9.5.4 compact_tables@git+https://github.com/Arksine/markdown-compact-tables@v1.0.0 +./pymdown-extras \ No newline at end of file diff --git a/docs/pymdown-extras/collapse_code.py b/docs/pymdown-extras/collapse_code.py new file mode 100644 index 0000000..2f00016 --- /dev/null +++ b/docs/pymdown-extras/collapse_code.py @@ -0,0 +1,129 @@ +# The MIT License (MIT) +# +# Copyright (c) 2014 - 2023 Isaac Muse +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + +# flake8: noqa + +"""Collapsible code.""" +import xml.etree.ElementTree as etree +from markdown import util as mutil +import re +from pymdownx.blocks.block import Block +from pymdownx.blocks import BlocksExtension + +# Fenced block placeholder for SuperFences +FENCED_BLOCK_RE = re.compile( + r'^([\> ]*){}({}){}$'.format( + mutil.HTML_PLACEHOLDER[0], + mutil.HTML_PLACEHOLDER[1:-1] % r'([0-9]+)', + mutil.HTML_PLACEHOLDER[-1] + ) +) + + +class CollapseCode(Block): + """Collapse code.""" + + NAME = 'collapse-code' + + def on_init(self): + """Handle initialization.""" + + # Track tab group count across the entire page. + if 'collapse_code_count' not in self.tracker: + self.tracker['collapse_code_count'] = 0 + + self.expand = self.config['expand_text'] + if not isinstance(self.expand, str): + raise ValueError("'expand_text' must be a string") + + self.collapse = self.config['collapse_text'] + if not isinstance(self.collapse, str): + raise ValueError("'collapse_text' must be a string") + + self.expand_title = self.config['expand_title'] + if not isinstance(self.expand_title, str): + raise ValueError("'expand_title' must be a string") + + self.collapse_title = self.config['collapse_title'] + if not isinstance(self.collapse_title, str): + raise ValueError("'collapse_title' must be a string") + + def on_create(self, parent): + """Create the element.""" + + self.count = self.tracker['collapse_code_count'] + self.tracker['collapse_code_count'] += 1 + el = etree.SubElement(parent, 'div', {'class': 'collapse-code'}) + etree.SubElement( + el, + 'input', + { + "type": "checkbox", + "id": "__collapse{}".format(self.count), + "name": "__collapse{}".format(self.count), + 'checked': 'checked' + } + ) + return el + + def on_end(self, block): + """Convert non list items to details.""" + + el = etree.SubElement(block, 'div', {'class': 'code-footer'}) + attrs = {'for': '__collapse{}'.format(self.count), 'class': 'expand', 'tabindex': '0'} + if self.expand_title: + attrs['title'] = self.expand_title + expand = etree.SubElement(el, 'label', attrs) + expand.text = self.expand + + attrs = {'for': '__collapse{}'.format(self.count), 'class': 'collapse', 'tabindex': '0'} + if self.collapse_title: + attrs['title'] = self.collapse_title + collapse = etree.SubElement(el, 'label', attrs) + collapse.text = self.collapse + + +class CollapseCodeExtension(BlocksExtension): + """Admonition Blocks Extension.""" + + def __init__(self, *args, **kwargs): + """Initialize.""" + + self.config = { + 'expand_text': ['Expand', "Set the text for the expand button."], + 'collapse_text': ['Collapse', "Set the text for the collapse button."], + 'expand_title': ['expand', "Set the text for the expand title."], + 'collapse_title': ['collapse', "Set the text for the collapse title."] + } + + super().__init__(*args, **kwargs) + + def extendMarkdownBlocks(self, md, blocks): + """Extend Markdown blocks.""" + + blocks.register(CollapseCode, self.getConfigs()) + + +def makeExtension(*args, **kwargs): + """Return extension.""" + + return CollapseCodeExtension(*args, **kwargs) diff --git a/docs/pymdown-extras/setup.py b/docs/pymdown-extras/setup.py new file mode 100644 index 0000000..6468ef4 --- /dev/null +++ b/docs/pymdown-extras/setup.py @@ -0,0 +1,7 @@ +from setuptools import setup +setup( + name='pymdown_extras', + version='1.0.0', + py_modules=['collapse_code'], + install_requires=['pymdown-extensions>=10.7'], +) diff --git a/mkdocs.yml b/mkdocs.yml index b3646e3..88336a6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -112,6 +112,9 @@ markdown_extensions: title: "Parameters" - tables - compact_tables: - auto_insert_break: true + auto_insert_break: false + - collapse_code: + expand_text: '' + collapse_text: '' extra_css: - src/css/extras.css \ No newline at end of file