From ac4a913be3aec1a45fddb406b18cd1f989bc267d Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Tue, 3 Aug 2021 14:43:52 +0200 Subject: [PATCH] doc/common/requirements: Toggle hub table. This makes it possible to hide/unhide the compatibility table. It is adapted from the sphinxcontrib-contentui extension: https://github.com/ulrobix/sphinxcontrib-contentui --- doc/common/conf.py | 1 + doc/common/extensions/requirements.css | 44 ++++++++++++++ doc/common/extensions/requirements.js | 33 +++++++++++ doc/common/extensions/requirements.py | 79 ++++++++++++++++++++++++++ doc/main/iodevices/index.rst | 6 +- doc/main/micropython/umath.rst | 6 +- 6 files changed, 161 insertions(+), 8 deletions(-) create mode 100644 doc/common/extensions/requirements.css create mode 100644 doc/common/extensions/requirements.js create mode 100644 doc/common/extensions/requirements.py diff --git a/doc/common/conf.py b/doc/common/conf.py index 8bff9ea..2d6c957 100644 --- a/doc/common/conf.py +++ b/doc/common/conf.py @@ -60,6 +60,7 @@ extensions = [ 'sphinx.ext.mathjax', 'color', 'classlink', + 'requirements', 'requirements-static', ] diff --git a/doc/common/extensions/requirements.css b/doc/common/extensions/requirements.css new file mode 100644 index 0000000..e295b4f --- /dev/null +++ b/doc/common/extensions/requirements.css @@ -0,0 +1,44 @@ +/*MIT License + +Copyright (c) 2017 Robert, https://github.com/ulrobix/sphinxcontrib-contentui + +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. */ + +.toggle-header { + display: block; + float: right; + clear: both; + cursor: pointer; +} +.toggle-header p {display: inline;} +.toggle-header strong {color: #2980b9 } + +.toggle-header:after { + content: "Compatibility ▼"; +} + +.toggle-header.open:after { + content: "▲"; +} + +.toggle-content { + display: none; + margin-bottom: 0px; +} + diff --git a/doc/common/extensions/requirements.js b/doc/common/extensions/requirements.js new file mode 100644 index 0000000..cebc079 --- /dev/null +++ b/doc/common/extensions/requirements.js @@ -0,0 +1,33 @@ +/*MIT License + +Copyright (c) 2017 Robert, https://github.com/ulrobix/sphinxcontrib-contentui + +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. */ + +$(function() { + /** + * Toggle logic + */ + $('.toggle-content').hide() + $('.toggle-header').click(function () { + $(this).toggleClass("open"); + $(this).next('.toggle-content').toggle('400'); + }) +}); + diff --git a/doc/common/extensions/requirements.py b/doc/common/extensions/requirements.py new file mode 100644 index 0000000..d202a3a --- /dev/null +++ b/doc/common/extensions/requirements.py @@ -0,0 +1,79 @@ +# MIT License + +# Copyright (c) 2017 Robert, https://github.com/ulrobix/sphinxcontrib-requirements + +# 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. + + +import os +from docutils.parsers.rst import Directive, directives +from docutils import nodes +from docutils.statemachine import StringList +from sphinx.util.osutil import copyfile +from sphinx.util import logging + + +CSS_FILE = 'requirements.css' +JS_FILE = 'requirements.js' + + +class PybricksRequirementsDirective(Directive): + has_content = True + option_spec = {'header': directives.unchanged} + + required_arguments = 0 + optional_arguments = 10 + + def run(self): + node = nodes.container() + node['classes'].append('toggle-content') + + par = nodes.container() + par['classes'].append('toggle-header') + + content = '.. pybricks-requirements-static:: ' + " ".join(self.arguments) + + self.state.nested_parse(StringList([content]), self.content_offset, node) + + return [par, node] + + +def add_assets(app): + app.add_css_file(CSS_FILE) + app.add_js_file(JS_FILE) + + +def copy_assets(app, exception): + if app.builder.name not in ['html', 'readthedocs'] or exception: + return + logger = logging.getLogger(__name__) + logger.info('Copying requirements stylesheet/javascript... ', nonl=True) + dest = os.path.join(app.builder.outdir, '_static', CSS_FILE) + source = os.path.join(os.path.abspath(os.path.dirname(__file__)), CSS_FILE) + copyfile(source, dest) + dest = os.path.join(app.builder.outdir, '_static', JS_FILE) + source = os.path.join(os.path.abspath(os.path.dirname(__file__)), JS_FILE) + copyfile(source, dest) + logger.info('done') + + +def setup(app): + app.add_directive('pybricks-requirements', PybricksRequirementsDirective) + app.connect('builder-inited', add_assets) + app.connect('build-finished', copy_assets) diff --git a/doc/main/iodevices/index.rst b/doc/main/iodevices/index.rst index 17b618e..b37d3a6 100644 --- a/doc/main/iodevices/index.rst +++ b/doc/main/iodevices/index.rst @@ -9,11 +9,9 @@ pupdevice +.. pybricks-requirements:: pybricks-iodevices -This module has classes for generic input/output devices. It is available on -these hubs: - -.. pybricks-requirements-static:: pybricks-iodevices +This module has classes for generic input/output devices. .. pybricks-classlink:: PUPDevice diff --git a/doc/main/micropython/umath.rst b/doc/main/micropython/umath.rst index 6477f1e..716abbb 100644 --- a/doc/main/micropython/umath.rst +++ b/doc/main/micropython/umath.rst @@ -1,11 +1,9 @@ :mod:`umath ` -- Math functions ============================================================ +.. pybricks-requirements:: stm32-extra stm32-float + This MicroPython module is similar to the `math module`_ in Python. -It is available on these hubs: - -.. pybricks-requirements-static:: stm32-extra stm32-float - .. module:: umath