# evennia.help.utils

Resources for indexing help entries and for splitting help entries into sub-categories.

This is used primarily by the default help command.

`evennia.help.utils.``help_search_with_index`(query, candidate_entries, suggestion_maxnum=5, fields=None)

  Lunr-powered fast index search and suggestion wrapper. See https://lunrjs.com/.

  Parameters

    - query (str) – The query to search for.

    - candidate_entries (list) – This is the body of possible entities to search. Each must have a property .search_index_entry that returns a dict with all keys in the fields arg.

    - suggestion_maxnum (int) – How many matches to allow at most in a multi-match.

    - fields (list, optional) – A list of Lunr field mappings **{“field_name”: str, “boost”: int}**. See the Lunr documentation for more details. The field name must exist in the dicts returned by .search_index_entry of the candidates. If not given, a default setup is used, prefering keys > aliases > category > tags.

  Returns

    tuple –

    A tuple (matches, suggestions), each a list, where the suggestion_maxnum limits

      how many suggestions are included.

`evennia.help.utils.``parse_entry_for_subcategories`(entry)

  Parse a command docstring for special sub-category blocks:

  Parameters

    entry (str) – A help entry to parse

  Returns

    dict –

    The dict is a mapping that splits the entry into subcategories. This

      will always hold a key None for the main help entry and zero or more keys holding the subcategories. Each is itself a dict with a key None for the main text of that subcategory followed by any sub-sub-categories down to a max-depth of 5.

  Example:

      '''
      Main topic text

      # SUBTOPICS

      ## foo

      A subcategory of the main entry, accessible as **help topic foo**
      (or using /, like **help topic/foo**)

      ## bar

      Another subcategory, accessed as **help topic bar**
      (or **help topic/bar**)

      ### moo

      A subcategory of bar, accessed as **help bar moo**
      (or **help bar/moo**)

      #### dum

      A subcategory of moo, accessed **help bar moo dum**
      (or **help bar/moo/dum**)

      '''

  This will result in this returned entry structure:

      {
         None: "Main topic text":
         "foo": {
              None: "main topic/foo text"
         },
         "bar": {
              None: "Main topic/bar text",
              "moo": {
                  None: "topic/bar/moo text"
                  "dum": {
                      None: "topic/bar/moo/dum text"
                  }
              }
         }
      }