pyodide-mkdocs-theme 0.1.0__py3-none-any.whl

pyodide_mkdocs_theme/__init__.py

@@ -0,0 +1,34 @@
+"""
+Pyodide-MkDocs-Theme is a theme for MkDocs that allows building websites integrating, on the client side:
+
+- IDEs (code editor),
+- Interactive Python consoles,
+- An online judge for testing user-written functions, associated with corrections and remarks,
+- And some other features (qcms, ...).
+
+## Guarantees:
+
+    - No cookies
+    - No registration
+    - Created by teachers for teachers
+
+This project is a redesign of the prototype [`pyodide-mkdocs`](https://bouillotvincent.gitlab.io/pyodide-mkdocs/) initially created by [Vincent Bouillot](https://gitlab.com/bouillotvincent/).
+
+## How it works:
+
+The technology enabling this feat is called [Pyodide](https://pyodide.org/en/stable/). It is associated with JavaScript elements, such as [jquery.terminal](https://terminal.jcubic.pl/api_reference.php) and [ACE Editor](https://ace.c9.io/).
+
+Pyodide uses WebAssembly to bridge between Python and JavaScript and provide an environment for manipulating the JavaScript DOM with Python, or vice versa for manipulating Python from JavaScript.
+
+
+## Links:
+
+* [GitLab repository](https://gitlab.com/frederic-zinelli/pyodide-mkdocs-theme)
+* [Documentation](http://frederic-zinelli.gitlab.io/pyodide-mkdocs-theme/) (french only)
+
+
+
+![IDE capture example](http://frederic-zinelli.gitlab.io/pyodide-mkdocs-theme/assets/pyodide-mkdocs-theme-ex.png)
+
+"""
+

pyodide_mkdocs_theme/__main__.py

@@ -0,0 +1,166 @@
+"""
+pyodide-mkdocs-theme
+Copyleft GNU GPLv3 🄯 2024 Frédéric Zinelli
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.
+If not, see <https://www.gnu.org/licenses/>.
+"""
+
+from argparse import ArgumentParser
+from .__version__ import __version__
+
+
+
+parser = ArgumentParser(
+    'pyodide_mkdocs_theme',
+    description="Scripts for pyodide-mkdocs-theme",
+    epilog="""Copyleft GNU GPLv3 🄯 2024 Frédéric Zinelli
+
+This program comes with ABSOLUTELY NO WARRANTY."""
+)
+parser.add_argument(
+    '-V', '--version', action='version', version=f'pyodide-mkdocs-theme {__version__}'
+)
+parser.add_argument(
+    '-yml', action='store_true', help='Print a base configuration for the mkdocs.yml file.'
+)
+
+def main():
+    args = parser.parse_args()
+    print(args)
+
+    if args.yml:
+        display_yml()
+
+
+
+
+def display_yml():
+    print('''
+# Voici un exemple presque complet de configuration pour un fichier
+# mkdocs.yml utilisant pyodide-mkdocs-theme.
+
+site_url: "{>> L'adresse de votre site web ici <<}"
+site_name: "{>> Titre pour votre site <<}"
+# site_description: "(optionnel)"
+# repo_url: "(optionnel)"
+# edit_uri: "(optionnel)"
+
+# Copyright "CC BY-NC-SA"
+copyright: |
+  <p xmlns:cc="http://creativecommons.org/ns#"
+  xmlns:dct="http://purl.org/dc/terms/">Partage ou adaptation possible selon les conditions de la
+  licence <a
+  href="http://creativecommons.org/licenses/by-nc-sa/4.0/?ref=chooser-v1"
+  target="_blank" rel="license noopener noreferrer"
+  style="display:inline-block;"> CC BY-NC-SA 4.0 <img
+  style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
+  src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1"><img
+  style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
+  src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1"><img
+  style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
+  src="https://mirrors.creativecommons.org/presskit/icons/nc.svg?ref=chooser-v1"><img
+  style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
+  src="https://mirrors.creativecommons.org/presskit/icons/sa.svg?ref=chooser-v1"></a></p>
+
+
+docs_dir: docs
+
+nav:
+  - "Accueil": index.md
+# - ...
+
+# Pour supprimer certains fichiers markdown de la navigation (pattern shell):
+# not_in_nav: |
+#   */**/*.md
+
+theme:
+  name: pyodide-mkdocs-theme
+
+# features:
+#   - navigation.instant      # Ne surtout pas activer cette option !
+
+
+markdown_extensions:
+
+  # Extensions indispensables pour le thème:
+  - md_in_html              # !!REQUIS!!
+  - admonition              # !!REQUIS!! Blocs colorés:  !!! info "ma remarque"
+  - attr_list               # !!REQUIS!! Un peu de CSS et des attributs HTML, ex: { #id .class style="display:none" }
+  - pymdownx.details        # !!REQUIS!! Admonition: ??? -> peuvent se déplier ; ???+ -> peuvent se replier.
+  - pymdownx.emoji:         # !!REQUIS!! Émojis:  :boom:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight      # !!REQUIS!! Coloration syntaxique du code
+  - pymdownx.inlinehilite   # !!REQUIS!! Coloration syntaxique pour les "code spans": `#!python  code_python`
+  - pymdownx.snippets:      # !!REQUIS!! Inclusion de fichiers externe.
+      check_paths: true     # Fortement conseillé...
+  - pymdownx.superfences    # !!REQUIS!!
+  - pymdownx.arithmatex:    # !!REQUIS!!
+      generic: true
+  - pymdownx.striphtml:
+      strip_js_on_attributes: false     # !!REQUIS!!
+      strip_attributes: ""              # !!REQUIS!!
+
+
+  # Extensions conseillées:
+  - meta
+  - abbr
+  - def_list                # Les listes de définition.
+  - footnotes               # Notes[^1] de bas de page.  [^1]: ma note.
+  - pymdownx.caret          # Passage ^^souligné^^ ou en ^exposant^.
+  - pymdownx.mark           # Passage ==surligné==.
+  - pymdownx.tilde          # Passage ~~barré~~ ou en ~indice~.
+  - pymdownx.tasklist:      # Cases à cocher  - [ ]  et - [x]
+      custom_checkbox: false
+      clickable_checkbox: true
+  - pymdownx.tabbed:        # Volets glissants:  === "Mon volet"
+      alternate_style: true # Meilleure compatibilité pour mobiles
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+  - pymdownx.keys           # Touches du clavier:  ++ctrl+d++
+  - toc:
+      toc_depth: 0          # Si vous voulez supprimer la ToC (table of content) de la page
+
+
+# Configuration minimale pour les plugins
+plugins:
+  - awesome-pages:          # Pas indispensable, mais... (pip install mkdocs-awesome-pages-plugin)
+      collapse_single_pages: true
+
+  - material/search         # Les plugins de material-mkdocs doivent être préfixés!
+
+  - exclude:                # (pip install mkdocs-exclude)
+      glob:                 # Patterns identifiant des pages à ne pas inclure dans le build.
+        - sous_dossier/**/*REM.md   # Les fichiers de remarques DOIVENT être exclus
+        - sous_dossier/**/*.py      # Les fichiers python DOIVENT être exclus
+
+  - exclude-search:         # (pip install mkdocs-exclude-search)
+      exclude:              # Pour les fichiers inclus dans le build, que la recherche ne doit pas indexer
+        - bac_a_sable.md
+
+  - pyodide_macros          # !!REQUIS!!
+
+
+validation:                 # Si mkdocs est lancé en mode strict (mkdocs ... --strict), les warnings lèveront une erreur
+  omitted_files: warn
+  unrecognized_links: warn
+
+''')
+
+
+
+if __name__ == '__main__':
+    main()

pyodide_mkdocs_theme/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pyodide_mkdocs_theme/pyodide_macros/__init__.py

@@ -0,0 +1,21 @@
+"""
+pyodide-mkdocs-theme
+Copyleft GNU GPLv3 🄯 2024 Frédéric Zinelli
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.
+If not, see <https://www.gnu.org/licenses/>.
+"""
+
+
+from .plugin.pyodide_macros_plugin import PyodideMacrosPlugin

pyodide_mkdocs_theme/pyodide_macros/exceptions.py

@@ -0,0 +1,25 @@
+"""
+pyodide-mkdocs-theme
+Copyleft GNU GPLv3 🄯 2024 Frédéric Zinelli
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.
+If not, see <https://www.gnu.org/licenses/>.
+"""
+
+from mkdocs.exceptions import ConfigurationError
+
+
+class PyodideConfigurationError(ConfigurationError):
+    """ Something went wrong in the Pyodide theme itself """
+

pyodide_mkdocs_theme/pyodide_macros/html_builder/__init__.py

@@ -0,0 +1,45 @@
+"""
+pyodide-mkdocs-theme
+Copyleft GNU GPLv3 🄯 2024 Frédéric Zinelli
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.
+If not, see <https://www.gnu.org/licenses/>.
+"""
+
+"""
+Objects to facilitate building html elements.
+
+Usage:
+    Import the module as a namespace and use the functions. This allows to keep the type
+    hints, the docstrings and the function signature when coding.
+"""
+# Using a package to control what functions/elements are seen through autocompletion
+# suggestions when coding.
+
+# pylint: disable=all
+
+from ._html_builder import (
+    input,
+    img,
+
+    a,
+    button,
+    code,
+    div,
+    script,
+    span,
+    svg,
+    terminal,
+    tooltip,
+)

pyodide_mkdocs_theme/pyodide_macros/html_builder/_html_builder.py

@@ -0,0 +1,145 @@
+"""
+pyodide-mkdocs-theme
+Copyleft GNU GPLv3 🄯 2024 Frédéric Zinelli
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.
+If not, see <https://www.gnu.org/licenses/>.
+"""
+
+# pylint: disable=all
+
+from typing import Dict, Optional
+
+
+
+
+
+
+def html_builder_factory(template:str, allow_content):
+    def tagger(tag:str):
+        def html_builder(
+            content:str="",
+            *,
+            id:str='', kls:str="", attrs: Dict[str, str]=None,
+            **kwargs
+        ) -> str:
+            """
+            Build a the code for the given tag element.
+            The id and kls named arguments, and also all keyword arguments have precedence over the
+            content of the attrs dict. This dict allow to define hyphen separated attributes (like
+            "data-max_size" and so on).
+
+            NOTE: Using the @content argument on "mono tags" will raise ValueError.
+            """
+            if not allow_content and content:
+                raise ValueError(f"Cannot use content on {tag!r} tags ({content=!r})")
+
+            attrs = attrs or {}
+            attrs.update(kwargs)
+            if id:  attrs['id'] = id
+            if kls: attrs['class'] = kls
+
+            attributes = " ".join(
+                f'{ name }="{ value }"' #if name!='onclick' else f'{ name }={ value }'
+                for name,value in attrs.items()
+            )
+            code = template.format(tag=tag, content=content, attributes=attributes)
+            return code
+
+        return html_builder
+    return tagger
+
+
+
+mono_tag = html_builder_factory("<{tag} {attributes} />", False)
+bi_tag   = html_builder_factory("<{tag} {attributes}>{content}</{tag}>", True)
+
+
+
+
+input   = mono_tag('input')
+img     = mono_tag('img')
+
+a       = bi_tag('a')
+button  = bi_tag('button')
+code    = bi_tag('code')
+div     = bi_tag('div')
+script  = bi_tag('script')
+span    = bi_tag('span')
+svg     = bi_tag('svg')
+
+
+
+
+def tooltip(txt:str, width_em:Optional[int]=None, shift:int=50):
+    """
+    Generic CodEx tooltip builder. If width_em is falsy, use automatic width.
+    Th @shift argument is the % to use for the translation, 0% means the tooltip will got on the
+    right, 100% means it will go on the left. With 50 (default), it's centered below the original element
+    """
+    dct = {
+        'kls': 'tooltiptext',
+        'style': f'--tool_shift: {shift}%;',
+    }
+    if width_em:
+        dct['style'] += f"width:{ width_em }em;"
+
+    return span(txt, **dct)
+
+
+
+
+
+def terminal(term_id:str, kls:str, n_lines_h:int, **kw):
+    """
+    Build a terminal div with its button. If n_lines_h is falsy, the height of the div isn't
+    handled. Otherwise, it's the mac of n_lines_h and 5.
+    """
+
+    tip = tooltip(
+        "Tronquer ou non le feedback dans les terminaux (sortie standard & stacktrace / relancer le code pour appliquer)",
+        width_em=16, shift=90
+    )
+    btn_div = div(
+        _BTN_STDOUT_SVG + tip,
+        kls="stdout-ctrl tooltip"
+    )
+    if n_lines_h:
+        n_lines_h = max(n_lines_h, 5)
+        kw['style'] = f"--n-lines:{ n_lines_h };" + kw.get('style','')
+    kw['style'] = 'line-height:24px;' + kw.get('style','')
+
+    term_div = div(btn_div, id=term_id, kls=kls, **kw)
+    return term_div
+
+
+_BTN_STDOUT_SVG = '''
+<svg viewBox="0 0 24 24" fill="none"
+    stroke="var(--md-default-fg-color)" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+    xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg">
+<g>
+  <path d="M 4,21.4 V 2.6 C 4,2.3 4.3,2 4.6,2 h 11.65 c 0.16,0 0.31,0.06 0.42,0.18 l 3.15,3.15 C 19.94,5.44 20,5.59 20,5.75 V 21.4 C 20,21.73 19.73,22 19.4,22 H 4.6 C 4.3,22 4,21.73 4,21.4 Z" />
+  <path d="M 16,5.4 V 2.35 C 16,2.16 16.16,2 16.35,2 c 0.09,0 0.18,0.03 0.25,0.10 l 3.29,3.29 C 19.96,5.46 20,5.55 20,5.65 20,5.84 19.84,6 19.65,6 H 16.6 C 16.27,6 16,5.73 16,5.4 Z" />
+  <path d="m 8,9.25 h 8" />
+  <path d="M 7.9,13.25 H 15.9"/>
+  <path d="M 7.9,11.25 H 14.4" />
+  <path d="M 7.9,19.25 H 14.4" />
+  <path d="m 7.9,15.25 h 8" />
+  <path d="M 7.9,17.25 H 11.9" />
+  <path d="m 8,5.25 h 4" />
+  <path d="m 8,7.25 h 4" />
+</g>
+<g><path class="stdout-x-ray-svg" d="M 3,11.4 v 6 L 21,13.8 V 7.7 Z" style="fill:var(--md-default-bg-color);stroke-width:0;" /></g>
+</svg>
+'''.replace('\n',' ')       # needed otherwise insertion in admonitions fails... XD

pyodide_mkdocs_theme/pyodide_macros/macros/IDEs/__init__.py

@@ -0,0 +1,121 @@
+"""
+pyodide-mkdocs-theme
+Copyleft GNU GPLv3 🄯 2024 Frédéric Zinelli
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.
+If not, see <https://www.gnu.org/licenses/>.
+"""
+
+# pylint: disable=invalid-name, missing-module-docstring
+
+
+from functools import wraps
+import re
+from typing import Literal, Optional, Union
+
+from ...tools_and_constants import ScriptSection
+from ...parsing import build_code_fence
+from ...plugin.maestro_IDE import MaestroIDE
+from .ide_files_data import IdeFilesExtractor
+from .ide import Ide
+
+
+
+
+
+def _IDE_maker(env:MaestroIDE, mode:str):
+    """
+    @script_name: Partial path from the directory holding the sujet.md file, to the one holding
+                  all the other required files, ending with the common prefix for the exercice.
+                  Ex:   "exo" to extract:   "exo.py", "exo_corr.py", "exo_test.py", ...
+                      "sub_exA/exo" for:  "sub_exA/exo.py", "sub_exA/exo_corr.py", ...
+    @MAX:         Number of tries before the solution becomes visible (default=5).
+    @SANS:        String of spaces or coma separated python functions or modules/packages the
+                  user cannot use. By default, nothing is forbidden.
+                      - Every string section that matches a builtin callable forbid that function
+                        by replacing it with another function which will raise an error if called
+                      - Every string section prefixed with a fot forbids a method call. Here a
+                        simple string containment check is done opn the user's code, to check it
+                        does not contain the desired method name with the dot before it.
+                      - Any other string section is considered as a module name and doing an
+                        import (in any way/syntax) involving that name will raise an error.
+    @SIZE:        Max number of lines of the IDE (default=30).
+    @ID:          Optional. To use to differentiate two IDEs using the same python root file.
+    @WHITE:       String of spaces or coma separated python modules/packages that have to be
+                  preloaded before the code restrictions (@SANS) are applied.
+    @LOGS:        If True, failing assertions without feedback during the private tests will
+                  be augmented automatically with the code of the assertion itself. If None,
+                  use the global `show_code_on_failed_assertions` plugin value, defined in
+                  `mkdocs.yml`, to determine what to do (default=None).
+    @REC_LIMIT:   Setup a specific recursion limit value for the runtime (-1 if not used)
+    @TERM_H:      Number of lines to use for the terminal size (ignored for vertical terminals)
+    """
+
+    @wraps(_IDE_maker)
+    def wrapped(
+        script_name: str = "",
+        MAX: Union[int, Literal["+"]] = 5,
+        SANS: str = "",
+        SIZE: int = 30,
+        ID: int = None,
+        WHITE: str = "",
+        LOGS: Optional[bool] = None,
+        REC_LIMIT: int = -1,
+        TERM_H: int = 10,
+    ) -> str:
+        return Ide(
+            env, script_name, mode, MAX, SANS, SIZE, WHITE, ID, LOGS, REC_LIMIT, TERM_H
+        ).make_ide()
+
+    wrapped.__name__ = wrapped.__qualname__ = 'IDE' + mode.strip('_')
+    return wrapped
+
+
+
+
+def IDE(env:MaestroIDE):
+    """ To build editor+terminal on 2 rows """
+    return _IDE_maker(env, "")
+
+
+def IDEv(env:MaestroIDE):
+    """ To build editor+terminal on 2 columns """
+    return _IDE_maker(env, "_v")
+
+
+
+
+
+
+
+def section(env:MaestroIDE):
+    """
+    Insert the given section from the python file.
+    Note: To use only on python scripts holding all the sections for the IDE macros. For regular
+          files, use the `py` macro or regular code fences with file inclusions (for performances
+          reasons).
+    """
+    @wraps(section)
+    def _section(script_name:str, section_name:ScriptSection, ID:Optional[int]=None):
+        file_data = IdeFilesExtractor(env, script_name)
+        content = file_data.get_section(section_name)
+
+        id_pattern = "" if ID is None else rf",\s*ID\s*=\s*{ ID }\b\s*"
+        macro_pattern = rf"""['"]{ script_name }['"]\s*,\s*['"]{ section_name }['"]{ id_pattern }"""
+        ide_jinja_reg = re.compile( rf"section\(\s*{ macro_pattern }" )
+        indent = env.get_indent_in_current_page(ide_jinja_reg)
+        out = build_code_fence(content, indent, lang='python')
+        return out
+
+    return _section