diff --git a/docs/source/Evennia-API.md b/docs/source/Evennia-API.md index ec0d4e2d7e..e96df0446c 100644 --- a/docs/source/Evennia-API.md +++ b/docs/source/Evennia-API.md @@ -1,77 +1,98 @@ -# Evennia API +# API Summary + +[evennia](api:evennia) - library root +- [evennia.accounts](api:evennia.accounts) - the out-of-character entities representing players +- [evennia.commands](api:evennia.commands) - handle all inputs. Also includes default commands +- [evennia.comms](api:evennia.comms) - in-game channels and messaging +- [evennia.contrib](api:evennia.contrib) - game-specific tools and code contributed by the community +- [evennia.help](api:evennia.help) - in-game help system +- [evennia.locks](api:evennia.locks) - limiting access to various systems and resources +- [evennia.objects](api:evennia.objects) - all in-game entities, like Rooms, Characters, Exits etc +- [evennia.prototypes](api:evennia.prototypes) - customize entities using dicts +- [evennia.scripts](api:evennia.scripts) - all out-of-character game objects +- [evennia.server](api:evennia.server) - core Server and Portal programs, also network protocols +- [evennia.typeclasses](api:evennia.typeclasses) - core database-python bridge +- [evennia.utils](api:evennia.utils) - lots of useful coding tools and utilities +- [evennia.web](api:evennia.web) - webclient, website and other web resources -Evennia makes much of its programming tools available directly from the top-level `evennia` package. -This is often referred to as Evennia's "flat" [Application Programming -Interface](https://en.wikipedia.org/wiki/Application_programming_interface) (API). The flat API -tries to collect and bring the most commonly used resources to the front in a way where everything -is available at a glance (in a flat display), making it a good place to start to learn Evennia. +## Shortcuts -> Evennia's flat (and full) API can be perused through the auto-generated [API Library -refence](github:evennia). - -A good, interactive way to explore the flat API is to use [IPython](http://ipython.org/), a more -flexible version of the default Python shell. Inside your virtual environment you can install -IPython simply by - - pip install ipython - -Windows users should also install [PyReadline](http://ipython.org/pyreadline.html): - - pip install pyreadline - -With IPython installed, go to your game directory and run - - evennia shell - -This should give you the IPython shell automatically. Inside IPython -you then do - - import evennia - -Followed by - - evennia. - -That is, write `evennia.` and press the TAB key. What pops up is the contents of the `evennia` top- -level package - in other words [the "flat" API](github:evennia#the-flat-api). - - evennia.DefaultObject? - -Starting to write the name of an API entity and pressing `` will auto-complete the name. Adding -a question mark (`?`) to its name will show you its documentation. Append `??` to get the actual -source code. This way you can quickly explore Evennia and see what is available. +Evennia's 'flat API' has shortcuts to common tools, available by only importing `evennia`. +The flat API is defined in `__init__.py` [viewable here](github:evennia/__init__.py) -## To remember when importing from `evennia` +### Main config -Properties on the root of the `evennia` package are *not* modules in their own right. They are just -shortcut properties stored in the `evennia/__init__.py` module. That means that you cannot use dot- -notation to `import` nested module-names over `evennia`. The rule of thumb is that you cannot use -`import` for more than one level down. Hence you can do +- [evennia.settings_default](github:evennia/settings_default.py) - all settings (modify/override in `mygame/server/settings.py`) -```python - import evennia - print(evennia.default_cmds.CmdLook) -``` +### Search functions -or import one level down +- [evennia.search_account](api:evennia.utils.search#evennia.utils.search.search_account) +- [evennia.search_object](api:evennia.utils.search#evennia.utils.search.search_object) +- [evennia.search_object_by_tag](api:evennia.utils.search#evennia.utils.search_object_by_tag) +- [evennia.search_script](api:evennia.utils.search#evennia.utils.search_script) +- [evennia.search_channel](api:evennia.utils.search#evennia.utils.search_channel) +- [evennia.search_message](api:evennia.utils.search#evennia.utils.search_message) +- [evennia.search_help](api:evennia.utils.search#evennia.utils.search.search_help) -```python - from evennia import default_cmds - print(default_cmds.CmdLook) -``` +### Create functions -but you *cannot* import two levels down +- [evennia.create_account](api:evennia.utils.create#evennia.utils.create.create_account) +- [evennia.create_object](api:evennia.utils.create#evennia.utils.create.create_object) +- [evennia.create_script](api:evennia.utils.create#evennia.utils.create.create_script) +- [evennia.create_channel](api:evennia.utils.create#evennia.utils.create.create_channel) +- [evennia.create_help_entry](api:evennia.utils.create#evennia.utils.create.create_help_entry) +- [evennia.create_message](api:evennia.utils.create#evennia.utils.create.create_message) -```python - from evennia.default_cmds import CmdLook # error! -``` +### Typeclasses -This will give you an `ImportError` telling you that the module `default_cmds` cannot be found - -this is becasue `default_cmds` is just a *variable* stored in `evennia.__init__.py`; this cannot be -imported from. If you really want full control over which level of package you import you can always -bypass the root package and import directly from from the real location. For example -`evennia.DefaultObject` is a shortcut to `evennia.objects.objects.DefaultObject`. Using this full -path will have the import mechanism work normally. See `evennia/__init__.py` to see where the -package imports from. +- [evennia.Defaultaccount](api:evennia.accounts.accounts#evennia.accounts.accounts.DefaultAccount) - player account class ([docs](./Accounts)) +- [evennia.DefaultGuest](api:evennia.accounts.accounts#evennia.accounts.accounts.DefaultGuest) - base guest account class +- [evennia.DefaultObject](api:evennia.objects.objects#evennia.objects.objects.DefaultObject) - base class for all objects ([docs](./Objects)) +- [evennia.DefaultCharacter](api:evennia.objects.objects#evennia.objects.objects.DefaultCharacter) - base class for in-game characters ([docs](./Objects#Character)) +- [evennia.DefaultRoom](api:evennia.objects.objects#evennia.objects.objects.DefaultRoom) - base class for rooms ([docs](./Objects#Room)) +- [evennia.DefaultExit](api:evennia.objects.objects#evennia.objects.objects.DefaultExit) - base class for exits ([docs](./Objects#Exit)) +- [evennia.DefaultScript](api:evennia.scripts.scripts#evennia.scripts.scripts.DefaultScript) - base class for OOC-objects ([docs](./Scripts)) +- [evennia.DefaultChannel](api:evennia.comms.comms#evennia.comms.comms.DefaultChannel) - base class for in-game channels ([docs](./Communications)) + +### Commands + +- [evennia.Command](api:evennia.commands.command#evennia.commands.command.Command) - base [Command](./Commands) class. See also `evennia.default_cmds.MuxCommand` +- [evennia.CmdSet](api:evennia.commands.cmdset#evennia.commands.cmdset.CmdSet) - base [Cmdset](./Command-Sets) class +- [evennia.default_cmds](api:Default-Command-Help) - access all default command classes as properties +- [evennia.syscmdkeys](api:Commands#System-Commands) - access system command keys as properties + +### Utilities + +- [evennia.utils.utils](api:evennia.utils.utils) - mixed useful utilities +- [evennia.gametime](api:evennia.utils.gametime) - server run- and game time ([docs](./Coding-Utils#gametime)) +- [evennia.logger](api:evennia.utils.logger) - logging tools +- [evennia.ansi](api:evennia.utils.ansi) - ansi coloring tools +- [evennia.spawn](api:evennia.prototypes.spawner#evennia.prototypes.spawner.Spawn) - spawn/prototype system ([docs](./Spawner-and-Prototypes)) +- [evennia.lockfuncs](api:evennia.locks.lockfuncs) - default lock functions for access control ([docs](./Locks)) +- [evennia.EvMenu](api:evennia.utils.evmenu#evennia.utils.evmenu.EvMenu) - menu system ([docs](./EvMenu)) +- [evennia.EvTable](api:evennia.utils.evtable#evennia.utils.evtable.EvTable) - text table creater +- [evennia.EvForm](api:evennia.utils.evform#evennia.utils.evform.EvForm) - text form creator +- [evennia.EvEditor](api:evennia.utils.eveditor#evennia.utils.eveditor.EvEditor) - in game text line editor ([docs](./EvEditor)) + +### Global singleton handlers + +- [evennia.TICKER_HANDLER](api:evennia.scripts.tickerhandler) - allow objects subscribe to tickers ([docs](./TickerHandler)) +- [evennia.MONITOR_HANDLER](api:evennia.scripts.monitorhandler) - monitor changes ([docs](./MonitorHandler)) +- [evennia.CHANNEL_HANDLER](api:evennia.comms.channelhandler) - maintains channels +- [evennia.SESSION_HANDLER](api:evennia.server.sessionhandler) - manages all sessions + +### Database core models (for more advanced lookups) + +- [evennia.ObjectDB](api:evennia.objects.models#evennia.objects.models.ObjectDB) +- [evennia.accountDB](api:evennia.accounts.models#evennia.accounts.models.AccountDB) +- [evennia.ScriptDB](api:evennia.scripts.models#evennia.scripts.models.ScriptDB) +- [evennia.ChannelDB](api:evennia.comms.models#evennia.comms.models.ChannelDB) +- [evennia.Msg](api:evennia.comms.models#evennia.comms.models.Msg) +- evennia.managers - contains shortcuts to all database managers + +### Contributions + +- [evennia.contrib](https://github.com/evennia/evennia/blob/master/evennia/contrib/) - +game-specific contributions and plugins ([docs](https://github.com/evennia/evennia/blob/master/evennia/contrib/README.md)) diff --git a/docs/source/_templates/package.rst_t b/docs/source/_templates/package.rst_t index 1a268d41bb..1469b5805f 100644 --- a/docs/source/_templates/package.rst_t +++ b/docs/source/_templates/package.rst_t @@ -31,8 +31,7 @@ Module contents {% endif %} {%- if submodules %} -Modules -------- + {% if separatemodules %} {{ toctree(submodules) }} {%- else %} @@ -47,8 +46,6 @@ Modules {%- if subpackages %} -Packages/folders ----------------- {{ toctree(subpackages) }} {% endif %} diff --git a/docs/source/api/evennia.accounts.rst b/docs/source/api/evennia.accounts.rst index 08b689d3c1..a8a3173cfa 100644 --- a/docs/source/api/evennia.accounts.rst +++ b/docs/source/api/evennia.accounts.rst @@ -6,8 +6,7 @@ evennia.accounts :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.commands.default.rst b/docs/source/api/evennia.commands.default.rst index 596d5e56d9..0ed91c7571 100644 --- a/docs/source/api/evennia.commands.default.rst +++ b/docs/source/api/evennia.commands.default.rst @@ -6,8 +6,7 @@ evennia.commands.default :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.commands.rst b/docs/source/api/evennia.commands.rst index 56cd32e4b0..d88c62a7e1 100644 --- a/docs/source/api/evennia.commands.rst +++ b/docs/source/api/evennia.commands.rst @@ -6,8 +6,7 @@ evennia.commands :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 @@ -18,8 +17,6 @@ Modules evennia.commands.cmdsethandler evennia.commands.command -Packages/folders ----------------- .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.comms.rst b/docs/source/api/evennia.comms.rst index 5c3761d59f..df024da752 100644 --- a/docs/source/api/evennia.comms.rst +++ b/docs/source/api/evennia.comms.rst @@ -6,8 +6,7 @@ evennia.comms :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.contrib.ingame_python.rst b/docs/source/api/evennia.contrib.ingame_python.rst index 97d001a4d5..d3abba10b2 100644 --- a/docs/source/api/evennia.contrib.ingame_python.rst +++ b/docs/source/api/evennia.contrib.ingame_python.rst @@ -6,8 +6,7 @@ evennia.contrib.ingame\_python :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.contrib.rst b/docs/source/api/evennia.contrib.rst index 4b9868b707..a40992e283 100644 --- a/docs/source/api/evennia.contrib.rst +++ b/docs/source/api/evennia.contrib.rst @@ -6,8 +6,7 @@ evennia.contrib :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 @@ -39,8 +38,6 @@ Modules evennia.contrib.unixcommand evennia.contrib.wilderness -Packages/folders ----------------- .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.contrib.security.auditing.rst b/docs/source/api/evennia.contrib.security.auditing.rst index 7aac40dfda..fb6c40a1c4 100644 --- a/docs/source/api/evennia.contrib.security.auditing.rst +++ b/docs/source/api/evennia.contrib.security.auditing.rst @@ -6,8 +6,7 @@ evennia.contrib.security.auditing :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.contrib.security.rst b/docs/source/api/evennia.contrib.security.rst index fd2dcd0bab..4e6fef9eb8 100644 --- a/docs/source/api/evennia.contrib.security.rst +++ b/docs/source/api/evennia.contrib.security.rst @@ -6,8 +6,6 @@ evennia.contrib.security :undoc-members: :show-inheritance: -Packages/folders ----------------- .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.contrib.turnbattle.rst b/docs/source/api/evennia.contrib.turnbattle.rst index 96afa16375..03bb3737df 100644 --- a/docs/source/api/evennia.contrib.turnbattle.rst +++ b/docs/source/api/evennia.contrib.turnbattle.rst @@ -6,8 +6,7 @@ evennia.contrib.turnbattle :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.contrib.tutorial_examples.rst b/docs/source/api/evennia.contrib.tutorial_examples.rst index 9a01032d29..61be345a78 100644 --- a/docs/source/api/evennia.contrib.tutorial_examples.rst +++ b/docs/source/api/evennia.contrib.tutorial_examples.rst @@ -6,8 +6,7 @@ evennia.contrib.tutorial\_examples :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.contrib.tutorial_world.rst b/docs/source/api/evennia.contrib.tutorial_world.rst index 8ba65cb7ff..d7f29ea729 100644 --- a/docs/source/api/evennia.contrib.tutorial_world.rst +++ b/docs/source/api/evennia.contrib.tutorial_world.rst @@ -6,8 +6,7 @@ evennia.contrib.tutorial\_world :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.help.rst b/docs/source/api/evennia.help.rst index f04209b03f..cc9b4ac68c 100644 --- a/docs/source/api/evennia.help.rst +++ b/docs/source/api/evennia.help.rst @@ -6,8 +6,7 @@ evennia.help :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.locks.rst b/docs/source/api/evennia.locks.rst index a3836b60ef..5141ff2dd8 100644 --- a/docs/source/api/evennia.locks.rst +++ b/docs/source/api/evennia.locks.rst @@ -6,8 +6,7 @@ evennia.locks :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.objects.rst b/docs/source/api/evennia.objects.rst index 5d79d16c61..3f46bb249d 100644 --- a/docs/source/api/evennia.objects.rst +++ b/docs/source/api/evennia.objects.rst @@ -6,8 +6,7 @@ evennia.objects :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.prototypes.rst b/docs/source/api/evennia.prototypes.rst index 0c26fff595..6051fb58b5 100644 --- a/docs/source/api/evennia.prototypes.rst +++ b/docs/source/api/evennia.prototypes.rst @@ -6,8 +6,7 @@ evennia.prototypes :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.rst b/docs/source/api/evennia.rst index 3d00e40829..73909713b5 100644 --- a/docs/source/api/evennia.rst +++ b/docs/source/api/evennia.rst @@ -6,16 +6,13 @@ evennia :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 evennia.settings_default -Packages/folders ----------------- .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.scripts.rst b/docs/source/api/evennia.scripts.rst index 14c154ba09..6fab193f27 100644 --- a/docs/source/api/evennia.scripts.rst +++ b/docs/source/api/evennia.scripts.rst @@ -6,8 +6,7 @@ evennia.scripts :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.server.game_index_client.rst b/docs/source/api/evennia.server.game_index_client.rst index ca8a109482..fd0ed5954d 100644 --- a/docs/source/api/evennia.server.game_index_client.rst +++ b/docs/source/api/evennia.server.game_index_client.rst @@ -6,8 +6,7 @@ evennia.server.game\_index\_client :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.server.portal.rst b/docs/source/api/evennia.server.portal.rst index 7bd0dfa937..a0624dfd11 100644 --- a/docs/source/api/evennia.server.portal.rst +++ b/docs/source/api/evennia.server.portal.rst @@ -6,8 +6,7 @@ evennia.server.portal :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.server.profiling.rst b/docs/source/api/evennia.server.profiling.rst index 89068d7204..7e943d258a 100644 --- a/docs/source/api/evennia.server.profiling.rst +++ b/docs/source/api/evennia.server.profiling.rst @@ -6,8 +6,7 @@ evennia.server.profiling :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.server.rst b/docs/source/api/evennia.server.rst index 71ee526fda..149333d34a 100644 --- a/docs/source/api/evennia.server.rst +++ b/docs/source/api/evennia.server.rst @@ -6,8 +6,7 @@ evennia.server :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 @@ -30,8 +29,6 @@ Modules evennia.server.validators evennia.server.webserver -Packages/folders ----------------- .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.typeclasses.rst b/docs/source/api/evennia.typeclasses.rst index 1f3c8e7ce2..9abc0e14f9 100644 --- a/docs/source/api/evennia.typeclasses.rst +++ b/docs/source/api/evennia.typeclasses.rst @@ -6,8 +6,7 @@ evennia.typeclasses :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.utils.idmapper.rst b/docs/source/api/evennia.utils.idmapper.rst index 85b71586b7..d8b39a8184 100644 --- a/docs/source/api/evennia.utils.idmapper.rst +++ b/docs/source/api/evennia.utils.idmapper.rst @@ -6,8 +6,7 @@ evennia.utils.idmapper :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.utils.rst b/docs/source/api/evennia.utils.rst index 4647d2f350..12894e85f0 100644 --- a/docs/source/api/evennia.utils.rst +++ b/docs/source/api/evennia.utils.rst @@ -6,8 +6,7 @@ evennia.utils :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 @@ -34,8 +33,6 @@ Modules evennia.utils.utils evennia.utils.validatorfuncs -Packages/folders ----------------- .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.web.rst b/docs/source/api/evennia.web.rst index e63d01605e..bd4f8d2269 100644 --- a/docs/source/api/evennia.web.rst +++ b/docs/source/api/evennia.web.rst @@ -6,16 +6,13 @@ evennia.web :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 evennia.web.urls -Packages/folders ----------------- .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.web.utils.rst b/docs/source/api/evennia.web.utils.rst index 7b0888f9bd..96158143ea 100644 --- a/docs/source/api/evennia.web.utils.rst +++ b/docs/source/api/evennia.web.utils.rst @@ -6,8 +6,7 @@ evennia.web.utils :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.web.webclient.rst b/docs/source/api/evennia.web.webclient.rst index 7d41ba63f6..1f80bbf43b 100644 --- a/docs/source/api/evennia.web.webclient.rst +++ b/docs/source/api/evennia.web.webclient.rst @@ -6,8 +6,7 @@ evennia.web.webclient :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.web.website.rst b/docs/source/api/evennia.web.website.rst index 49c51de624..d64379eddf 100644 --- a/docs/source/api/evennia.web.website.rst +++ b/docs/source/api/evennia.web.website.rst @@ -6,8 +6,7 @@ evennia.web.website :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 @@ -17,8 +16,6 @@ Modules evennia.web.website.urls evennia.web.website.views -Packages/folders ----------------- .. toctree:: :maxdepth: 6 diff --git a/docs/source/api/evennia.web.website.templatetags.rst b/docs/source/api/evennia.web.website.templatetags.rst index ad420e1efc..466be51e36 100644 --- a/docs/source/api/evennia.web.website.templatetags.rst +++ b/docs/source/api/evennia.web.website.templatetags.rst @@ -6,8 +6,7 @@ evennia.web.website.templatetags :undoc-members: :show-inheritance: -Modules -------- + .. toctree:: :maxdepth: 6 diff --git a/docs/source/index.md b/docs/source/index.md index e6db4ece09..2b2d09ab78 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,10 +1,10 @@ # VERSION WARNING -> This is the static v0.95 documentation of Evennia, originally converted from the old +> This is the v0.95 documentation of Evennia, originally converted from the old > [evennia wiki](https://github.com/evennia/evennia/wiki/) at 2020-10-11 18:06:03.062022. > While we will fix outright mistakes, minor typos and visual conversion issues will _not_ be > addressed in this version. -> A new new refactored version of the docs are being prepared for the v3.0 of the documentation. +> A new and refactored version of the docs is being prepared for version 1.0 of Evennia. # Evennia Documentation @@ -22,7 +22,7 @@ time. - The [Builder Docs](./Builder-Docs) helps for starting to build a game world using Evennia. - The [Developer Central](./Developer-Central) describes how Evennia works and is used by coders. - The [Tutorials & Examples](./Tutorials) contains help pages on a step-by-step or tutorial format. -- The [API](api:evennia) documentation is created from the latest source code. +- The [API](./Evennia-API) documentation is created from the latest source code. - The [TOC](./toc) lists all regular documentation pages. [group]: https://groups.google.com/forum/#%21forum/evennia