# evennia.help.filehelp

The filehelp-system allows for defining help files outside of the game. These will be treated as non-command help entries and displayed in the same way as help entries created using the sethelp default command. After changing an entry on-disk you need to reload the server to have the change show in-game.

An filehelp file is a regular python module with dicts representing each help entry. If a list HELP_ENTRY_DICTS is found in the module, this should be a list of dicts. Otherwise all top-level dicts in the module will be assumed to be a help-entry dict.

Each help-entry dict is on the form

    {'key': <str>,
     'text': <str>,
     'category': <str>,   # optional, otherwise settings.DEFAULT_HELP_CATEGORY
     'aliases': <list>,   # optional
     'locks': <str>}      # optional, use access-type 'view'. Default is view:all()

The text** should be formatted on the same form as other help entry-texts and can contain **# subtopics** as normal.

New help-entry modules are added to the system by providing the python-path to the module to settings.FILE_HELP_ENTRY_MODULES. Note that if same-key entries are added, entries in latter modules will override that of earlier ones. Use settings.DEFAULT_HELP_CATEGORY** to customize what category is used if not set explicitly.

An example of the contents of a module:

    help_entry1 = {
        "key": "The Gods",   # case-insensitive, also partial-matching ('gods') works
        "aliases": ['pantheon', 'religion'],
        "category": "Lore",
        "locks": "view:all()",   # this is optional unless restricting access
        "text": '''
            The gods formed the world ...

            # Subtopics

            ## Pantheon

            ...

            ### God of love

            ...

            ### God of war

            ...

        '''
    }

    HELP_ENTRY_DICTS = [
        help_entry1,
        ...
    ]

class `evennia.help.filehelp.``FileHelpEntry`(key: str, aliases: list, help_category: str, entrytext: str, lock_storage: str)

  Bases: `object`

  Represents a help entry read from file. This mimics the api of the database-bound HelpEntry so that they can be used interchangeably in the help command.

  `key`: str
  `aliases`: list
  `help_category`: str
  `entrytext`: str
  `lock_storage`: str
  property `search_index_entry`

    Property for easily retaining a search index entry for this object.

  `locks`
  `web_get_detail_url`()

    Returns the URI path for a View that allows users to view details for this object.

    ex. Oscar (Character) = ‘/characters/oscar/1/’

    For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-detail’ would be referenced by this method.

    ex.

        url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/$',
            CharDetailView.as_view(), name='character-detail')

    If no View has been created and defined in urls.py, returns an HTML anchor.

    This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

    Returns

      path (str) – URI path to object detail page, if defined.

  `web_get_admin_url`()

    Returns the URI path for the Django Admin page for this object.

    ex. Account#1 = ‘/admin/accounts/accountdb/1/change/’

    Returns

      path (str) – URI path to Django Admin page for object.

  `access`(accessing_obj, access_type='view', default=True)

    Determines if another object has permission to access this help entry.

    Parameters

      - accessing_obj (Object or Account) – Entity trying to access this one.

      - access_type (str) – type of access sought.

      - default (bool) – What to return if no lock of access_type was found.

  `__init__`(key: str, aliases: list, help_category: str, entrytext: str, lock_storage: str) → None

    Initialize self. See help(type(self)) for accurate signature.

class `evennia.help.filehelp.``FileHelpStorageHandler`(help_file_modules=['world.help_entries'])

  Bases: `object`

  This reads and stores help entries for quick access. By default it reads modules from settings.FILE_HELP_ENTRY_MODULES.

  Note that this is not meant to any searching/lookup - that is all handled by the help command.

  `__init__`(help_file_modules=['world.help_entries'])

    Initialize the storage.

  `load`()

    Load/reload file-based help-entries from file.

  `all`(return_dict=False)

    Get all help entries.

    Parameters

      return_dict (bool) – Return a dict **{key: FileHelpEntry,…}**. Otherwise, return a list of **FileHelpEntry.

    Returns

      dict or list – Depending on the setting of **return_dict**.