pyodide-mkdocs-theme 5.3.6__tar.gz → 5.4.0__tar.gz

{pyodide_mkdocs_theme-5.3.6 → pyodide_mkdocs_theme-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyodide-mkdocs-theme
-Version: 5.3.6
+Version: 5.4.0
 Summary: Package embedding the necessary tools to host pyodide, ACE editors, jQuery terminals in mkdocs documentations
 License: GPL-3.0-or-later
 Keywords: mkdocs,mkdocs-plugin,pyodide,IDE,terminal

{pyodide_mkdocs_theme-5.3.6 → pyodide_mkdocs_theme-5.4.0}/pyodide_mkdocs_theme/__main__.py

@@ -67,9 +67,10 @@ parser.add_argument(
 parser.add_argument(
     '--lang', action='extend', nargs='*', choices=LANGS, default=[],
     help=f'Optional. Choices: { ", ".join(LANGS) }. '
-         'Print the base python code to customize some messages. '
-         'Can also be used with other arguments to get the information in languages other '
-         'than "fr", when relevant.'
+         'Can be used with other arguments to get the information/files in languages other '
+         'than "fr", when relevant. '
+         '([DEPRECATED]: Print the base python code to customize some messages. From PMT 5.3.0, '
+         "use the plugin's configuration to change PMT messages.)"
 )
 parser.add_argument(    # Effect strictly equivalent to --lang, but present for semantic
     '-M', '--macros', action='store_true',
@@ -247,8 +248,7 @@ def main():
         'plot':     'pyodide_plot.py',
         'py':       'docs/exo.py',
         'toolbox':  'toolbox.py',
-        'yml':      'mkdocs.yml',
-        'lang':     'main.py' ,
+        'yml':      'mkdocs.yml'
     }
 
     if args.basthonP5:
@@ -282,7 +282,10 @@ def main():
 
     if not did_some and args.lang:
         did_some = True
-        handle_one_file(args, 'lang')
+        print(
+            "From PMT 5.3.0, you should update Lang messages directly through the plugin's configuration. "
+            "The old `env.lang.overload` way is still supported, but it should not be used anymore."
+        )
 
 
     if raise_toolbox:

pyodide_mkdocs_theme-5.4.0/pyodide_mkdocs_theme/__version__.py

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

{pyodide_mkdocs_theme-5.3.6 → pyodide_mkdocs_theme-5.4.0}/pyodide_mkdocs_theme/pyodide_macros/macros/figure.py

@@ -22,9 +22,6 @@ If not, see <https://www.gnu.org/licenses/>.
 from functools import wraps
 from typing import Optional
 
-from mkdocs.exceptions import BuildError
-
-
 
 from ..tools_and_constants import MACROS_WITH_INDENTS, HtmlClass, P5BtnLocation
 from .. import html_builder as Html

{pyodide_mkdocs_theme-5.3.6 → pyodide_mkdocs_theme-5.4.0}/pyodide_mkdocs_theme/pyodide_macros/macros/ide_manager.py

@@ -548,87 +548,180 @@ class IdeManagerMdHtmlGenerator(IdeSectionsManager):
 
     def generate_id(self):
         """
-        Generate an id number for the current element, in the form:
+        Generate hash part of the html id for the current element, in the form:
 
             "{ self.PREFIX_ }{ 32 chars hex value }"
 
+        Uniqueness of the resulting hash is verified and PmtMacrosNonUniqueIdError is raised
+        if two identical hashes are encountered.
+
+        ---
+
         <br><br>
 
-        ## CONSTRAINTS:
+        ## CONSTRAINTS on the html ids:
 
-        - Unique to every runner used throughout the whole website.
-        - Stable, so that it can be used to identify what IDE goes with what file or what
+        1. Stable, so that it can be used to identify what IDE goes with what file or what
         localStorage data.
-        - For IDEs:
-            * It must be possible to differentiate IDEs from different pages using the same
-            base python file
-            * It must be possible to identify unambiguously IDEs in different pages that do
-            not use any python file.
+
+        2. Unique to every runner used throughout the whole website, and specifically for IDEs:
+            * IDEs using the same python file in different pages must have different ids.
+            * IDEs NOT using any python file must have different ids in any page.
+            * The uniqueness of the ids across different PMT projects should be "guaranteed"
+            if they are hosted on the same domain, so that IDEs of different projects do not
+            override each others in the localStorage.
+
+        3. It must be possible to guarantee the backward compatibility if the id values when
+        desired by the redactor. It may not be possible for all projects at the same time after
+        the update to 5.4+, but redactors should have a way to maintain them when it's possible.
+
+        4. If ever two identical ids from different projects are found at runtime (JS layer), the
+        user should be warned, with sufficient information to correct the problem (aka, adding an
+        ID argument to the IDE of the current project => this IDE must be fully identifiable).
+        This is not handled in the `generate_id` method.
+
+        ---
 
         <br><br>
 
-        ## STRATEGIES:
-
-            NOTE: The cache has been deactivated manually and isn't accessible to the user
-                  anymore, but the implementation still makes reference to it, if ever I put
-                  it back in place, one day... (unlikely: removed because mainly useless).
-
-        The string to hash is built in the following ways:
-        - For elements with python file(s):
-            * use the absolute path (unresolved) to the main side fail (first argument if
-              `py_names` is a varargs).
-            * non IDE macros see the macro name added to the string (to differentiate them
-              from IDEs, while keeping backward compatibility for IDEs' ids)
-            * the ID argument _will_ often be needed to differentiate the runners/macros,
-              while allowing cache capabilities without much ambiguity when the user is
-              adding, deleting or moving macro calls around in the md page.
-              This can be turned down with `build.activate_cache: false`: then all non IDE
-              macros fall back to the behavior below.
-            * IDEs specific: the "mode" (/_v) is appended to the string before hashing (legacy).
-
-        - For elements without a python file, or for non IDEs with `build.activate_cache: false`:
-            * use the page url, with the macro name, then a counter of that kind of macro calls.
-
-        Uniqueness of the resulting hash is verified and BuildError is raised if two identical
-        hashes are encountered.
+        ## RATIONALS:
+
+
+        An id redundancy can occur in the following cases:
+
+        * IDEs without python files at the same location in the docs_dir will result in
+        identical html ids, whatever the `ides_id_hash_mode` value.
+
+        * With `ides_id_hash_mode: relative`, ides at equivalent locations in the docs_dir
+        and using the same python file (name/location) and the same ID argument will result
+        in two identical html ids.
+
+        Note that, using `ides_id_hash_mode: legacy`, the redundancy is limited to the
+        intrinsic hash collision probability, so almost non existant. So no need to
+        disambiguate IDE WITH python files in that mode. Though, a project_id value will
+        still be needed to disambiguate entries in the localStorage when using the trashcan
+        button, if several PMT projects are hosted on the same domain.
+
+        So, the chosen strategies are  the following:
+
+        ---
+
+        For non IDEs elements:
+
+        - They don't have to worry about the multi-projects aspects. Ids unique throughout the
+        page are more than enough.
+        - Consistency of the generated ids through time is more important than anything else.
+        - The ids are built using:
+            * the page url (relative to site_dir)
+            * the macro name (so that the counts for IDEs is not affected by adding other
+            elements earlier in the page).
+            * a counter specific to the macro name and the page
+
+
+        For IDE elements:
+
+        - Priority must be given to the consistency of the ids through time, WHEN POSSIBLE.
+        - Second most important property is uniqueness across the localStorage, meaning handling
+        the multi-projects aspects is a "must have", at the best possible extent.
+
+        For IDE elements without associated python file:
+
+        - These are more often subject to side effects across different projects, because the
+        html ids are generated using the PAGE URL (relative to the site_dir), concatenated with
+        various things that are specific to the page or the macro. So different website with the
+        same relative URL _will_ clash in the localStorage. These require the use of a project_id
+        value.
+        - Note that the value of `ides_id_hash_mode` has no effect on these IDEs and these actually
+        behave the same way as IDEs with python files and `ides_id_hash_mode: relative` is used,
+        hence the previous point.
+
+        For IDE elements with a python file:
+
+        - The python file location is used in "unresolved" fashion, whatever the value of
+        `ides_id_hash_mode` is. Meaning: `xxx/A/../B/exo.py` is used as is, instead of resolving
+        it to `xxx/B/exo.py`. This allows to reduce the occurrences where the ID argument has to
+        be added to the macro call.
+        - Projects using `ides_id_hash_mode: legacy`, despite all the problems that go with it,
+        are not subject to localStorage ids clashes for these IDEs, BUT, the trashcan button still
+        requires the project_id value to differentiate the source of each entry.
+        <br>This means the user CAN maintain backward compatibility of the ids by skipping the
+        project_id part when building the hash, even if it has been provided for the trashcan
+        functionality. The `project_disambiguate_local_storage` option allow to control this.
+        - For legacy reasons (PM), ids for IDEv macros see the `"_v"` element added to the string
+        before the hash is computed. THIS IS NOT APPLIED to IDEv WITHOUT PYTHON FILE (PMT legacy).
+        - Projects using `ides_id_hash_mode: relative` ARE way more subject to ids clashes, so the
+        project_id has to be used.
+
+        For backward compatibility, the redactor has two options:
+        1. Set the project id of one project to `""` and maintain backward compatibility for this
+        project, and use a unique value for other projects. These will get new ids for all IDEs
+        with a python file and the localStorage content will be lost.
+        2. Set `project_disambiguate_local_storage` to False along with a project_id value for
+        each project. This is kinda "relying on luck", but could work well enough: the redactor
+        hopes a minimal number of clashes and waits for the users to signal the troubles when they
+        occur, so that they can fix the clashes individually by adding ID arguments where needed.
+
+        ---
+
+        ___NOTE about the cache:___
+
+        The cache has been deactivated manually and isn't accessible to the user anymore, but the
+        implementation still makes reference to it, if ever I put it back in place, one day...
+        (unlikely: removed because mainly useless, by now).
+
+
+        ___NOTE about `ides_id_hash_mode: legacy`:___
+
+        The `runner_path` (to the python file) used in that case is "absolute + unresolved".
+        <br>When building the site during a pipeline, the paths look like this:
+
+            /builds/frederic-zinelli/pyodide-mkdocs-theme/docs/redactors/sequential_examples/ide4.py
+
+        This has kind of "opposite" consequences:
+
+        1. The ids are automatically disambiguated considering different projects hosted in the same
+        GtiLab account/group, and probabilities of hashes collisions,event if not inexistant, are
+        probabilistically close to zero.
+
+        2. When using `mkdocs serve`:
+            - The ids during serve ARE NOT IDENTICAL to those of the same IDE on the online site.
+            - The localStorage during serve sees ALL the IDEs entries of ALL the projects on the
+            local machine.
         """
-        is_ide = PmtPyMacrosName.is_ide(self.MACRO_NAME)
+        is_ide      = PmtPyMacrosName.is_ide(self.MACRO_NAME)
+        is_relative = not self.env.is_legacy
+        runner_path = self.exo_py
+        has_py_file = bool(runner_path)
+        project_id  = self.env.project_id or ""
+
+        need_project_id = is_ide and self.env.project_disambiguate_local_storage and project_id and (
+            not has_py_file or is_relative
+        )
+        # The project_id is needed to disambiguate the html ids in the localStorage only if:
+        #   1. The element is an IDE
+        #   2. The user actually gave a value for env.project_id
+        #   3. The user _wants_ the project_id added to compute the html ids
+        #   4. Either...:
+        #       - the ides_id_hash_mode is set to relative
+        #       - Or there is no python file for the IDE
 
-        if self.exo_py and (is_ide or self.env.ACTIVATE_CACHE):
-            # IDE ids have to stay consistent with previous implementations, to not brake the
-            # localeStorage saves of the users.
+        project_id = f':_{ project_id }' * bool(need_project_id)
 
-            # The macro name is added in the string generating the hash for non IDE elements,
-            # so that using the same source file for different kind of macros won't generate
-            # equivalent hashes (ease the way for the users, _and_ more consistent with previous
-            # behaviors... Even if that is probably a breaking change).
-            less_ID_needs = "" if is_ide else ':'+self.MACRO_NAME
+        if has_py_file and (is_ide or self.env.ACTIVATE_CACHE):
 
-            runner_path   = self.exo_py
-            if is_ide and not HashPathMode.is_legacy(self.env):
-                # Avoid any dependency on the domain/site name, if needed:
+            less_ID_needs = "" if is_ide else ':'+self.MACRO_NAME
+            if is_ide and is_relative:
                 runner_path = Path(self.exo_py).relative_to(self.env.docs_dir_path)
 
-            to_hash = f"{ runner_path }{ self.IDE_VERT }{ less_ID_needs }"
-            # PROBLEM for IDEs in ides_id_hash_mode:"legacy":
-            #
-            #   `runner_path` is "absolute unresolved", in that case. When building the site during
-            #   a pipeline, the paths look like this:
-            #
-            #       /builds/frederic-zinelli/pyodide-mkdocs-theme/docs/redactors/sequential_examples/ide4.py
-            #
-            # This means the ids are disambiguated considering different projects hosted in the same
-            # GtiLab account/group, and probabilities of hashes collisions are not inexistant, but
-            # probabilistically close to zero.
+            to_hash = f"{ runner_path }{ self.IDE_VERT }{ less_ID_needs }{ project_id }"
 
         else:
             count   = self.env.macros_counters[ self.MACRO_NAME ].inc()
-            to_hash = f"{ self.env.page.url }-{ self.MACRO_NAME }-{ count }"
-                    # DO NOT lstrip, even if it looks ugly on the home page (nobody but me can see
-                    # it anyway... :rolleyes:), to keep implementation consistent for users...
+            to_hash = f"{ self.env.page.url }-{ self.MACRO_NAME }-{ count }{ project_id }"
+            # DO NOT lstrip `to_hash`, to keep implementation consistent for users, even if it
+            # looks ugly on the home page (url is ""). Nobody but me can see it anyway... :rolleyes:
 
         hashed = self.id_to_hash(to_hash)
-        # print(hashed, to_hash)
         return hashed
 
 
@@ -652,11 +745,11 @@ class IdeManagerMdHtmlGenerator(IdeSectionsManager):
                 "The same html id got generated twice.\n"
                 "If you are trying to use the same set of files for different macros calls, use "
                 "their ID argument (int >= 0) to disambiguate them.\n\n"
-            )+ self.env.ACTIVATE_CACHE*(
+            ) + self.env.ACTIVATE_CACHE * (
                 "If you are encountering this problem with macros other than IDE or IDEv and you "
                 "do not need some extra speed rendering-wise, you also can deactivate the PMT "
                f"cache, using `{ cache_option }: false`.\n\n"
-            )+(
+            ) + (
                f"ID values already in use:   { self.env.get_registered_ids_for(id_path) }\n"
                f"Id generated with:          { to_hash }\n{ self.env.log() }"
             )

{pyodide_mkdocs_theme-5.3.6 → pyodide_mkdocs_theme-5.4.0}/pyodide_mkdocs_theme/pyodide_macros/macros/qcm.py

@@ -22,8 +22,6 @@ from functools import wraps
 from textwrap import dedent
 from typing import Any, Dict, List, Tuple
 
-from mkdocs.exceptions import BuildError
-
 
 from ..pyodide_logger import logger
 from ..tools_and_constants import MACROS_WITH_INDENTS, HtmlClass, IdeConstants