Merge pull request #23 from realtimeprojects/branches/1.7

Branches/1.7

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: run CI checks
 on:
   # Runs on pushes targeting the default branch
   push:
-    branches: ["main"]
+    branches: ["main", "branches/*"]
 
 jobs:
   ci:

.github/workflows/static.yml

@@ -4,7 +4,7 @@ name: Deploy static content to Pages
 on:
   # Runs on pushes targeting the default branch
   push:
-    branches: ["main"]
+    branches: ["main", "branches/*"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

docs/definitions.md

@@ -13,7 +13,7 @@ term:section
 term:summary
 :   The summary is a list of all defined terms in a section.
 
-    It contains links to their <term:definition|definitions> and <term:reference|references>.
+    It contains links to their <term:definitions> and <term:references>.
 
 term:definition
 :   The definition of a term in a definition lists.

docs/releases.md

@@ -1,5 +1,22 @@
 # Release Notes
 
+## v1.7.1
+| ~2024-10-11~
+
+-   Fix #22: Plural configuration did not work.
+
+## v1.7.0
+| ~2024-10-10~
+
+-   Glossary: Add section and term as attributes of Entry
+-   Links: Add name attribute containing "{section:term}"
+-   Fix html entity handling.
+-   Basic support of [handling plurals](usage/linking.md#handling-plurals). See
+    also [#18](https://github.com/realtimeprojects/mkdocs-ezglossary/issues/18)
+-   Fix #21: Support [ignoring case for terms](usage/linking.md#case-sensitivity)
+-   Fix #20: Usage of `tooltip:short`
+-   Fix #19: Usage of `inline_refs:list`
+
 ## v1.6.10
 | ~2024-05-08~
 

docs/usage/definition.md

@@ -78,7 +78,7 @@ to use them anyway:
 | `&` (as first character)       | `&`     |
 | `/`                            | `/`     | 
 | `|`                            | `¦`    | 
-| `"`                            | `"`     | 
+| `"`                            | `"`    | 
 | `<`                            | `&#lt;`     | 
 | `>`                            | `&#gt;`     | 
 | `:`                            | `&#58;`     | 

docs/usage/linking.md

@@ -21,6 +21,26 @@ syntax. This will produce a link to the definition in your documentation:
     -   See the <demo:my_term1> for definition of term 1
     -   See the <demo:my term 2> for definition of term 1
 
+## Case sensitivity
+> starting from version `1.7.0` [beta]
+
+By default, this term definitions and references are case-sensitive, i.e. you need to use
+the exact spelling in your links as used in your term definition.
+
+By setting <configuration:ignore_case> to `true`, the plugin will ignore the case in order
+to find definitions for your links.
+
+!!! Example
+
+    ``` yaml
+    plugins:
+        search
+        ezglossary:
+            ignore_case: true
+    ```
+
+    -   See the <demo:MY_term1> for definition of term 1
+
 ## Individual reference texts
 
 By default the <term:term> is used as text for the link, however,
@@ -45,6 +65,61 @@ you can override the term using the `|` modifier:
     | <term:section\|glossary sections> | ...  |
     ```
 
+## Handling plurals
+> starting from version `1.7.0a2` (not stable released yet)
+
+A most common problem when linking to glossary terms is that you want to use
+the plural form of the word in the link text while linking to the term in singular.
+
+!!! Example
+
+    Definition:
+
+    ``` markdown
+    GPU
+    :   A GPU is a ....
+    ```
+
+    Linking:
+
+    ``` markdown
+    Many <term:GPUs> support ...
+    ```
+
+!!! Note
+
+    At this point of time, plural lookup is only available for the english language.
+
+    However, future versions may support additional langugaes (with your help). Furthermore
+    a feature is planned to allow you to define your own rules for the lookup.
+
+### Lookup using the inflect library
+
+The [inflect library](https://github.com/jaraco/inflect) supports converting plurals to singulars,
+it has some advantages and drawbacks. If you want to use this library to convert plurals to singulars,
+you can add the following entry to the configuration:
+
+``` yaml
+plugins:
+    search
+    ezglossary:
+      plurals: inflect
+```
+
+### Looking up using the plugin's logic
+
+This plugin has an own implementation logic to lookup singulars, which might not be perfect as well,
+but might catch some edge cases which the inflect library does not catch.
+
+Try the own implementation by adding this configuration entry:
+
+``` yaml
+plugins:
+    search
+    ezglossary:
+      plurals: en
+```
+
 ## Using markdown links
 > starting from version `1.6.0`
 
@@ -107,15 +182,15 @@ tooltips should be displayed with a preview on the definition:
 plugins:
     search
     ezglossary:
-      tooltip: [none, heading, full]
+      tooltip: [none, short, full]
 ```
 
 Options:
 
 none
 :   Tooltips are disabled
 
-heading
+short
 :   The <term:reference> link shows the first line of the definition as a tooltip
     (link title)
 
@@ -140,3 +215,11 @@ full
 
 configuration:tooltip
 :   Configure [tooltips](#tooltips) for reference links. Default is `none`.
+
+configuration:plurals
+:   Configure if and how the plugin shall lookup the term in singular if a plural
+    is provided in the link text. See [handling plurals](#handling-plurals) for more details.
+
+configuration:ignore_case
+:   Set to `true` to ignore the case for terms in the definition lookup.
+

mkdocs.yml

@@ -57,8 +57,10 @@ plugins:
       list_references: true
       markdown_links: true
       inline_refs: none
+      ignore_case: true
       tooltip: full
       use_default: true
+      plurals: en
       sections:
         - setting
         - term

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs-ezglossary-plugin
-version = 1.6.10
+version = 1.7.1
 description = manage multiple glossaries in mkdocs
 keywords = mkdocs, glossary, plugin, references, links
 long_description = file: README.md
@@ -22,6 +22,7 @@ include_package_data = True
 install_requires =
     mkdocs >= 1.1.0
     jinja2
+    inflect
 
 [options.package_data]
 mkdocs_ezglossary_plugin=

src/mkdocs_ezglossary_plugin/glossary.py

@@ -1,6 +1,5 @@
 import hashlib
 import logging
-import html
 
 log = logging.getLogger(__name__)
 
@@ -12,7 +11,7 @@ def get_id(section: str, term: str, linktype: str, n: str):
 class Entry:
     """ An entry in the glossary. """
 
-    def __init__(self, target, page, definition):
+    def __init__(self, target, page, definition, section, term):
         self.target = target
         """ The anchor to directly point to this specific link. """
 
@@ -22,23 +21,30 @@ def __init__(self, target, page, definition):
         self.definition = definition
         """ The definition of the term. """
 
+        self.section = section
+        """ The section of the term of this entry. (Since `v1.7.0a1`) """
+
+        self.term = term
+        """ The term of this entry. (Since v1.7.0a1) """
+
     def __repr__(self):
         return self.page.url
 
 
 class Glossary:
     """ The complete glossary for all sections """
 
-    def __init__(self):
+    def __init__(self, ignore_case):
         self.clear()
+        self.ignore_case = ignore_case
 
     def add(self, section, term, linktype, page, definition=None, anchor=None):
-        term = html.unescape(term.strip())
+        term = term.strip()
         log.debug(f"glossary.add({section}, {term}, {linktype}, '{definition}', {anchor})")
         links = self._links(section, term, linktype)
         _id = get_id(section, term, linktype, len(links))
         anchor = _id if anchor is None else anchor
-        links[_id] = Entry(anchor, page, definition)
+        links[_id] = Entry(anchor, page, definition, section, term)
         return _id
 
     def has(self, section: str) -> bool:
@@ -74,7 +80,7 @@ def get(self, section: str, term: str, linktype: str) -> list[Entry]:
             Returns:
                 A list of either `definitions` or `references` for the given term.
         """
-        links = self._links(section, html.unescape(term), linktype).values()
+        links = self._links(section, term, linktype).values()
         return list(links)
 
     def definition(self, section: str, term: str) -> str:
@@ -89,7 +95,7 @@ def definition(self, section: str, term: str) -> str:
             Returns:
                 The definition of the term
         """
-        defs = self.get(section, html.unescape(term), 'defs')
+        defs = self.get(section, term, 'defs')
         if not defs:
             return ""
         return defs[0].definition
@@ -116,8 +122,13 @@ def _links(self, section, term, linktype):
 
     def _term(self, section, term):
         _section = self._section(section)
-        if term not in _section:
-            self._section(section)[term] = {'defs': {}, 'refs': {}}
+        if term in _section:
+            return self._section(section)[term]
+        if self.ignore_case:
+            for candidate in _section.keys():
+                if candidate.upper() == term.upper():
+                    return self._section(section)[candidate]
+        self._section(section)[term] = {'defs': {}, 'refs': {}}
         return self._section(section)[term]
 
     def _section(self, section):