Tweak look of API header

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.
+## Shortcuts
-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.
 
-> Evennia's flat (and full) API can be perused through the auto-generated [API Library
+Evennia's 'flat API' has shortcuts to common tools, available by only importing `evennia`.
-refence](github:evennia).
+The flat API is defined in `__init__.py` [viewable here](github:evennia/__init__.py)
-
-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.<TAB>
-
-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 `<TAB>` 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.
 
 
-## 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
+- [evennia.settings_default](github:evennia/settings_default.py) - all settings (modify/override in `mygame/server/settings.py`)
-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
 
-```python
+### Search functions
-    import evennia
-    print(evennia.default_cmds.CmdLook)
-```
 
-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
+### Create functions
-    from evennia import default_cmds
-    print(default_cmds.CmdLook)
-```
 
-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
+### Typeclasses
-     from evennia.default_cmds import CmdLook # error!
-```
 
-This will give you an `ImportError` telling you that the module `default_cmds` cannot be found -
+- [evennia.Defaultaccount](api:evennia.accounts.accounts#evennia.accounts.accounts.DefaultAccount) - player account class ([docs](./Accounts))
-this is becasue `default_cmds` is just a *variable* stored in `evennia.__init__.py`; this cannot be
+- [evennia.DefaultGuest](api:evennia.accounts.accounts#evennia.accounts.accounts.DefaultGuest) - base guest account class
-imported from. If you really want full control over which level of package you import you can always
+- [evennia.DefaultObject](api:evennia.objects.objects#evennia.objects.objects.DefaultObject) - base class for all objects ([docs](./Objects))
-bypass the root package and import directly from from the real location. For example
+- [evennia.DefaultCharacter](api:evennia.objects.objects#evennia.objects.objects.DefaultCharacter) - base class for in-game characters ([docs](./Objects#Character))
-`evennia.DefaultObject` is a shortcut to `evennia.objects.objects.DefaultObject`. Using this full
+- [evennia.DefaultRoom](api:evennia.objects.objects#evennia.objects.objects.DefaultRoom) - base class for rooms ([docs](./Objects#Room))
-path will have the import mechanism work normally. See `evennia/__init__.py` to see where the
+- [evennia.DefaultExit](api:evennia.objects.objects#evennia.objects.objects.DefaultExit) - base class for exits ([docs](./Objects#Exit))
-package imports from.
+- [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))

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 %}

docs/source/api/evennia.accounts.rst

@@ -6,8 +6,7 @@ evennia.accounts
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.commands.default.rst

@@ -6,8 +6,7 @@ evennia.commands.default
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

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

docs/source/api/evennia.comms.rst

@@ -6,8 +6,7 @@ evennia.comms
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.contrib.ingame_python.rst

@@ -6,8 +6,7 @@ evennia.contrib.ingame\_python
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

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

docs/source/api/evennia.contrib.security.auditing.rst

@@ -6,8 +6,7 @@ evennia.contrib.security.auditing
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.contrib.security.rst

@@ -6,8 +6,6 @@ evennia.contrib.security
    :undoc-members:
    :show-inheritance:
 
-Packages/folders
-----------------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.contrib.turnbattle.rst

@@ -6,8 +6,7 @@ evennia.contrib.turnbattle
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.contrib.tutorial_examples.rst

@@ -6,8 +6,7 @@ evennia.contrib.tutorial\_examples
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.contrib.tutorial_world.rst

@@ -6,8 +6,7 @@ evennia.contrib.tutorial\_world
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.help.rst

@@ -6,8 +6,7 @@ evennia.help
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.locks.rst

@@ -6,8 +6,7 @@ evennia.locks
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.objects.rst

@@ -6,8 +6,7 @@ evennia.objects
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.prototypes.rst

@@ -6,8 +6,7 @@ evennia.prototypes
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

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

docs/source/api/evennia.scripts.rst

@@ -6,8 +6,7 @@ evennia.scripts
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

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

docs/source/api/evennia.server.portal.rst

@@ -6,8 +6,7 @@ evennia.server.portal
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.server.profiling.rst

@@ -6,8 +6,7 @@ evennia.server.profiling
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

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

docs/source/api/evennia.typeclasses.rst

@@ -6,8 +6,7 @@ evennia.typeclasses
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.utils.idmapper.rst

@@ -6,8 +6,7 @@ evennia.utils.idmapper
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

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

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

docs/source/api/evennia.web.utils.rst

@@ -6,8 +6,7 @@ evennia.web.utils
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

docs/source/api/evennia.web.webclient.rst

@@ -6,8 +6,7 @@ evennia.web.webclient
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

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

docs/source/api/evennia.web.website.templatetags.rst

@@ -6,8 +6,7 @@ evennia.web.website.templatetags
    :undoc-members:
    :show-inheritance:
 
-Modules
+
--------
 
 .. toctree::
    :maxdepth: 6

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