Changeset a5f3cc1 in rtems-central


Ignore:
Timestamp:
May 6, 2020, 8:31:57 AM (6 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
833470c
Parents:
fa46b668
git-author:
Sebastian Huber <sebastian.huber@…> (05/06/20 08:31:57)
git-committer:
Sebastian Huber <sebastian.huber@…> (05/28/20 08:37:29)
Message:

spec: Use item mapper for glossary terms

Files:
1 added
36 edited

Legend:

Unmodified
Added
Removed
  • rtemsqual/content.py

    rfa46b668 ra5f3cc1  
    3030import re
    3131import textwrap
    32 from typing import Callable, ContextManager, Iterator, List, Optional, Union
    33 
    34 from rtemsqual.items import Item
     32from typing import Any, Callable, ContextManager, Iterator, List, Optional, \
     33    Union
     34
     35from rtemsqual.items import Item, ItemMapper
    3536
    3637AddContext = Callable[["Content"], ContextManager[None]]
     
    327328
    328329
    329 class MacroToSphinx:
    330     """ This class expands specification item macros to Sphinx markup. """
    331     def __init__(self):
    332         self._terms = {}
    333 
    334     def set_terms(self, terms):
    335         """ Sets the glossary of terms used for macro expansion. """
    336         self._terms = terms
    337 
    338     def substitute(self, text):
    339         """
    340         Substitutes all specification item macros contained in the text.
    341         """
    342         return re.sub(r"@@|@([a-z]+){([^}]+)}", self, text)
    343 
    344     def __call__(self, match):
    345         name = match.group(1)
    346         if name:
    347             roles = {
    348                 "term":
    349                 lambda x: ":term:`" + self._terms[x]["glossary-term"] + "`"
    350             }
    351             return roles[name](match.group(2))
    352         assert match.group(0) == "@@"
    353         return "@"
     330class SphinxMapper(ItemMapper):
     331    """ Sphinx mapper. """
     332    def __init__(self, item: Item):
     333        super().__init__(item)
     334
     335    def get_value(self, _item: Item, _path: str, value: Any, key: str,
     336                  _index: Optional[int]) -> Any:
     337        """ Gets a value by key and optional index. """
     338        # pylint: disable=no-self-use
     339        if key == "glossary-term":
     340            return f":term:`{value[key]}`"
     341        raise KeyError
    354342
    355343
  • rtemsqual/glossary.py

    rfa46b668 ra5f3cc1  
    2727import glob
    2828import re
    29 from typing import Dict
     29from typing import Any, Dict, Optional
    3030
    31 from rtemsqual.content import MacroToSphinx, SphinxContent
    32 from rtemsqual.items import Item, ItemCache
     31from rtemsqual.content import SphinxContent, SphinxMapper
     32from rtemsqual.items import Item, ItemCache, ItemMapper
    3333
    3434ItemMap = Dict[str, Item]
     
    5555    with content.indent():
    5656        content.append(":sorted:")
    57     macro_to_sphinx = MacroToSphinx()
    58     macro_to_sphinx.set_terms(terms)
    5957    for item in sorted(terms.values(),
    6058                       key=lambda x: x["glossary-term"].lower()):
    61         text = macro_to_sphinx.substitute(item["text"].strip())
    6259        content.register_license_and_copyrights_of_item(item)
    6360        with content.indent():
     61            text = SphinxMapper(item).substitute(item["text"])
    6462            content.add_definition_item(item["glossary-term"], text)
    6563    content.add_licence_and_copyrights()
     
    8381
    8482
    85 def _resolve_glossary_term(document_terms: ItemMap, project_terms: ItemMap,
    86                            term: Item) -> None:
    87     for match in re.findall(r"@@|@([a-z]+){([^}]+)}", term["text"]):
    88         if match[1] and match[1] not in document_terms:
    89             new_term = project_terms[match[1]]
    90             document_terms[match[1]] = new_term
    91             _resolve_glossary_term(document_terms, project_terms, new_term)
     83class _GlossaryMapper(ItemMapper):
     84    def __init__(self, item: Item, document_terms: ItemMap):
     85        super().__init__(item)
     86        self._document_terms = document_terms
     87
     88    def get_value(self, item: Item, _path: str, _value: Any, key: str,
     89                  _index: Optional[int]) -> Any:
     90        """ Recursively adds glossary terms to the document terms. """
     91        if key == "glossary-term":
     92            if item.uid not in self._document_terms:
     93                self._document_terms[item.uid] = item
     94                _GlossaryMapper(item,
     95                                self._document_terms).substitute(item["text"])
     96        # The value of this substitute is unused.
     97        return ""
    9298
    9399
    94 def _resolve_glossary_terms(document_terms: ItemMap,
    95                             project_terms: ItemMap) -> None:
     100def _resolve_glossary_terms(document_terms: ItemMap) -> None:
    96101    for term in list(document_terms.values()):
    97         _resolve_glossary_term(document_terms, project_terms, term)
     102        _GlossaryMapper(term, document_terms).substitute(term["text"])
    98103
    99104
     
    107112    for path in config["rest-source-paths"]:
    108113        _find_glossary_terms(path, document_terms, project_terms)
    109     _resolve_glossary_terms(document_terms, project_terms)
     114    _resolve_glossary_terms(document_terms)
    110115    content = _generate_glossary_content(document_terms)
    111116    content.write(config["target"])
  • rtemsqual/tests/spec-glossary/glos/term/t.yml

    rfa46b668 ra5f3cc1  
    88  uid: ../g
    99text: |
    10   Term text @@@term{/glos/term/u}.
     10  Term text $$${/glos/term/u:/glossary-term} ${/glos/term/t:/glossary-term}
     11  ${/glos/term/u:/glossary-type}.
    1112type: glossary
  • rtemsqual/tests/test_content_sphinx.py

    rfa46b668 ra5f3cc1  
    2727import pytest
    2828
    29 from rtemsqual.content import SphinxContent
    30 from rtemsqual.content import MacroToSphinx
    31 from rtemsqual.items import Item, ItemCache
    32 
    33 
    34 class EmptyCache(ItemCache):
    35     def __init__(self):
    36         return
     29from rtemsqual.content import SphinxContent, SphinxMapper
     30from rtemsqual.items import Item, ItemCache, ItemMapper
     31from rtemsqual.tests.util import create_item_cache_config_and_copy_spec
    3732
    3833
     
    123118
    124119
    125 def test_substitute():
    126     macro_to_sphinx = MacroToSphinx()
    127     data = {}
    128     data["glossary-term"] = "y"
    129     terms = {}
    130     terms["x"] = Item(EmptyCache(), "x", data)
    131     macro_to_sphinx.set_terms(terms)
    132     assert "@" == macro_to_sphinx.substitute("@@")
    133     assert "@x" == macro_to_sphinx.substitute("@x")
     120def test_substitute(tmpdir):
     121    config = create_item_cache_config_and_copy_spec(tmpdir, "spec-sphinx")
     122    item_cache = ItemCache(config)
     123    mapper = SphinxMapper(item_cache["/x"])
    134124    with pytest.raises(KeyError):
    135         macro_to_sphinx.substitute("@x{y}")
    136     assert ":term:`y`" == macro_to_sphinx.substitute("@term{x}")
     125        mapper.substitute("${x:/y}")
     126    assert ":term:`y`" == mapper.substitute("${x:/glossary-term}")
  • rtemsqual/tests/test_glossary.py

    rfa46b668 ra5f3cc1  
    6464
    6565    T
    66         Term text @:term:`U`.
     66        Term text $:term:`U` :term:`T`
     67        term.
    6768
    6869    U
     
    8687
    8788    T
    88         Term text @:term:`U`.
     89        Term text $:term:`U` :term:`T`
     90        term.
    8991
    9092    U
  • spec/glos/term/asr.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/asynchronoussignalroutine}.
     11  An acronym for ${asynchronoussignalroutine:/glossary-term}.
    1212type: glossary
  • spec/glos/term/assemblerlanguage.yml

    rfa46b668 ra5f3cc1  
    1111  The assembler language is a programming language which can be translated very
    1212  easily into machine code and data.  For this project assembler languages are
    13   restricted to languages accepted by the @term{/glos/term/gnu} assembler
     13  restricted to languages accepted by the ${gnu:/glossary-term} assembler
    1414  program for the target architectures.
    1515type: glossary
  • spec/glos/term/atomicoperations.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   Atomic operations are defined in terms of @term{/glos/term/c11}.
     11  Atomic operations are defined in terms of ${c11:/glossary-term}.
    1212type: glossary
  • spec/glos/term/bsp.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/boardsupportpackage}.
     11  An acronym for ${boardsupportpackage:/glossary-term}.
    1212type: glossary
  • spec/glos/term/clanguage.yml

    rfa46b668 ra5f3cc1  
    1010text: |
    1111  The C language for this project is defined in terms of
    12   @term{/glos/term/c11}.
     12  ${c11:/glossary-term}.
    1313type: glossary
  • spec/glos/term/cpu.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/centralprocessingunit}.
     11  An acronym for ${centralprocessingunit:/glossary-term}.
    1212type: glossary
  • spec/glos/term/errorcode.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   This term has the same meaning as @term{/glos/term/statuscode}.
     11  This term has the same meaning as ${statuscode:/glossary-term}.
    1212type: glossary
  • spec/glos/term/fifo.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/firstinfirstout}.
     11  An acronym for ${firstinfirstout:/glossary-term}.
    1212type: glossary
  • spec/glos/term/gnat.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   *GNAT* is the @term{/glos/term/gnu} compiler for Ada, integrated into the
    12   @term{/glos/term/gcc}.
     11  *GNAT* is the ${gnu:/glossary-term} compiler for Ada, integrated into the
     12  ${gcc:/glossary-term}.
    1313type: glossary
  • spec/glos/term/interruptservice.yml

    rfa46b668 ra5f3cc1  
    1010text: |
    1111  An *interrupt service* consists of an
    12   @term{/glos/term/interruptserviceroutine} which is called with a user
     12  ${interruptserviceroutine:/glossary-term} which is called with a user
    1313  provided argument upon reception of an interrupt service request.  The
    1414  routine is invoked in interrupt context.  Interrupt service requests may have
    1515  a priority and an affinity to a set of processors.  An *interrupt service* is
    16   a @term{/glos/term/softwarecomponent}.
     16  a ${softwarecomponent:/glossary-term}.
    1717type: glossary
  • spec/glos/term/isr.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/interruptserviceroutine}.
     11  An acronym for ${interruptserviceroutine:/glossary-term}.
    1212type: glossary
  • spec/glos/term/mpci.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/multiprocessorcommunicationsinterfacelayer}.
     11  An acronym for ${multiprocessorcommunicationsinterfacelayer:/glossary-term}.
    1212type: glossary
  • spec/glos/term/partition.yml

    rfa46b668 ra5f3cc1  
    1515     area of memory.
    1616
    17   2. A @term{/glos/term/cluster} with a cardinality of one is a partition.
     17  2. A ${cluster:/glossary-term} with a cardinality of one is a partition.
    1818type: glossary
  • spec/glos/term/ptcb.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/partitioncontrolblock}.
     11  An acronym for ${partitioncontrolblock:/glossary-term}.
    1212type: glossary
  • spec/glos/term/pxcb.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/proxycontrolblock}.
     11  An acronym for ${proxycontrolblock:/glossary-term}.
    1212type: glossary
  • spec/glos/term/qcb.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/messagequeuecontrolblock}.
     11  An acronym for ${messagequeuecontrolblock:/glossary-term}.
    1212type: glossary
  • spec/glos/term/returncode.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   This term has the same meaning as @term{/glos/term/statuscode}.
     11  This term has the same meaning as ${statuscode:/glossary-term}.
    1212type: glossary
  • spec/glos/term/returnvalue.yml

    rfa46b668 ra5f3cc1  
    1010text: |
    1111  The value returned by a function.  A return value may be a
    12   @term{/glos/term/statuscode}.
     12  ${statuscode:/glossary-term}.
    1313type: glossary
  • spec/glos/term/rncb.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/regioncontrolblock}.
     11  An acronym for ${regioncontrolblock:/glossary-term}.
    1212type: glossary
  • spec/glos/term/smcb.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/semaphorecontrolblock}.
     11  An acronym for ${semaphorecontrolblock:/glossary-term}.
    1212type: glossary
  • spec/glos/term/softwarecomponent.yml

    rfa46b668 ra5f3cc1  
    1313  following items and nothing else:
    1414
    15   * @term{/glos/term/softwareunit}
     15  * ${softwareunit:/glossary-term}
    1616
    17   * explicitly defined @term{/glos/term/elf} symbol in a
    18     @term{/glos/term/sourcecode} file
     17  * explicitly defined ${elf:/glossary-term} symbol in a
     18    ${sourcecode:/glossary-term} file
    1919
    20   * @term{/glos/term/assemblerlanguage} data in a source code file
     20  * ${assemblerlanguage:/glossary-term} data in a source code file
    2121
    22   * @term{/glos/term/clanguage} object with static storage duration
     22  * ${clanguage:/glossary-term} object with static storage duration
    2323
    2424  * C language object with thread-local storage duration
    2525
    26   * @term{/glos/term/thread}
     26  * ${thread:/glossary-term}
    2727
    28   * @term{/glos/term/interruptservice}
     28  * ${interruptservice:/glossary-term}
    2929
    3030  * collection of *software components* (this is a software architecture
     
    3333  Please note that explicitly defined ELF symbols and assembler language
    3434  data are considered a software component only if they are defined in a
    35   @term{/glos/term/sourcecode} file.  For example, this rules out symbols
     35  ${sourcecode:/glossary-term} file.  For example, this rules out symbols
    3636  and data generated as side-effects by the toolchain (compiler, assembler,
    3737  linker) such as jump tables, linker trampolines, exception frame information,
  • spec/glos/term/softwareitem.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   This term has the same meaning as @term{/glos/term/softwareproduct}.
     11  This term has the same meaning as ${softwareproduct:/glossary-term}.
    1212type: glossary
  • spec/glos/term/softwareproduct.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   The *software product* is the @term{/glos/term/rtems} real-time operating system.
     11  The *software product* is the ${rtems:/glossary-term} real-time operating system.
    1212type: glossary
  • spec/glos/term/softwareunit.yml

    rfa46b668 ra5f3cc1  
    1313  the following items and nothing else:
    1414
    15   * @term{/glos/term/assemblerlanguage} function in a
    16     @term{/glos/term/sourcecode} file
     15  * ${assemblerlanguage:/glossary-term} function in a
     16    ${sourcecode:/glossary-term} file
    1717
    18   * @term{/glos/term/clanguage} function (external and internal linkage)
     18  * ${clanguage:/glossary-term} function (external and internal linkage)
    1919
    20   A *software unit* is a @term{/glos/term/softwarecomponent}.
     20  A *software unit* is a ${softwarecomponent:/glossary-term}.
    2121type: glossary
  • spec/glos/term/statuscode.yml

    rfa46b668 ra5f3cc1  
    1111  A status code indicates the completion status of an operation.  For
    1212  example most RTEMS directives return a status code through the
    13   @term{/glos/term/returnvalue} to indicate a successful operation or error
     13  ${returnvalue:/glossary-term} to indicate a successful operation or error
    1414  conditions.
    1515type: glossary
  • spec/glos/term/task.yml

    rfa46b668 ra5f3cc1  
    1818  It consists normally of a set of registers and a stack.  The scheduler
    1919  assigns processors to a subset of the ready tasks.  The terms task and
    20   @term{/glos/term/thread} are synonym in RTEMS.  The term task is used
     20  ${thread:/glossary-term} are synonym in RTEMS.  The term task is used
    2121  throughout the Classic API, however, internally in the operating system
    2222  implementation and the POSIX API the term thread is used.
    2323
    24   A *task* is a @term{/glos/term/softwarecomponent}.
     24  A *task* is a ${softwarecomponent:/glossary-term}.
    2525type: glossary
  • spec/glos/term/tcb.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/taskcontrolblock}.
     11  An acronym for ${taskcontrolblock:/glossary-term}.
    1212type: glossary
  • spec/glos/term/thread.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   This term has the same meaning as @term{/glos/term/task}.
     11  This term has the same meaning as ${task:/glossary-term}.
    1212type: glossary
  • spec/glos/term/tls.yml

    rfa46b668 ra5f3cc1  
    1010text: |
    1111  An acronym for Thread-Local Storage :cite:`Drepper:2013:TLS`.  TLS is
    12   available in @term{/glos/term/c11} and @term{/glos/term/cxx11}.  The support for TLS depends
     12  available in ${c11:/glossary-term} and ${cxx11:/glossary-term}.  The support for TLS depends
    1313  on the CPU port :cite:`RTEMS:CPU`.
    1414type: glossary
  • spec/glos/term/tmcb.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   An acronym for @term{/glos/term/timercontrolblock}.
     11  An acronym for ${timercontrolblock:/glossary-term}.
    1212type: glossary
  • spec/glos/term/usersupplied.yml

    rfa46b668 ra5f3cc1  
    99  uid: ../general
    1010text: |
    11   This term has the same meaning as @term{/glos/term/userprovided}.
     11  This term has the same meaning as ${userprovided:/glossary-term}.
    1212type: glossary
Note: See TracChangeset for help on using the changeset viewer.