From d229ff024cd397bf2cb4d1e26b4017f3d7584ce5 Mon Sep 17 00:00:00 2001 From: Griatch Date: Tue, 26 Oct 2021 21:14:33 +0200 Subject: [PATCH] Convert master docs to use MyST --- docs/Makefile | 19 +- docs/README.md | 4 +- docs/pylib/api_rst2md.py | 31 + docs/pylib/auto_link_remapper.py | 119 +- docs/pylib/copy_from_wiki.py | 21 +- docs/pylib/fmtwidth.py | 45 + docs/pylib/update_default_cmd_index.py | 111 + .../A-voice-operated-elevator-using-events.md | 6 +- docs/source/Accounts.md | 24 +- docs/source/Add-a-wiki-on-your-website.md | 2 +- docs/source/Adding-Command-Tutorial.md | 14 +- .../Adding-Object-Typeclass-Tutorial.md | 10 +- docs/source/Administrative-Docs.md | 56 +- docs/source/Arxcode-installing-help.md | 8 +- docs/source/Async-Process.md | 4 +- docs/source/Attributes.md | 32 +- docs/source/Banning.md | 4 +- docs/source/Batch-Code-Processor.md | 4 +- docs/source/Batch-Command-Processor.md | 6 +- docs/source/Batch-Processors.md | 6 +- .../Bootstrap-Components-and-Utilities.md | 6 +- docs/source/Builder-Docs.md | 30 +- docs/source/Building-Permissions.md | 4 +- docs/source/Building-Quickstart.md | 20 +- docs/source/Building-a-mech-tutorial.md | 10 +- docs/source/Client-Support-Grid.md | 137 +- docs/source/Coding-FAQ.md | 42 +- docs/source/Coding-Introduction.md | 10 +- docs/source/Coding-Utils.md | 36 +- docs/source/Command-Cooldown.md | 4 +- docs/source/Command-Duration.md | 6 +- docs/source/Command-Prompt.md | 2 +- docs/source/Command-Sets.md | 26 +- docs/source/Command-System.md | 10 +- docs/source/Commands.md | 56 +- docs/source/Communications.md | 16 +- docs/source/Connection-Screen.md | 6 +- docs/source/Continuous-Integration.md | 2 +- docs/source/Contributing-Docs.md | 998 +++---- docs/source/Contributing.md | 4 +- docs/source/Coordinates.md | 2 +- docs/source/Custom-Protocols.md | 10 +- docs/source/Customize-channels.md | 2 +- docs/source/Default-Command-Help.md | 2538 ----------------- docs/source/Default-Commands.md | 107 + docs/source/Default-Exit-Errors.md | 10 +- docs/source/Developer-Central.md | 134 +- docs/source/Directory-Overview.md | 42 +- docs/source/Docs-refactoring.md | 6 +- docs/source/Dynamic-In-Game-Map.md | 8 +- docs/source/EvMenu.md | 34 +- docs/source/EvMore.md | 2 +- docs/source/Evennia-API.md | 118 +- docs/source/Evennia-Introduction.md | 26 +- docs/source/Evennia-for-MUSH-Users.md | 14 +- .../Evennia-for-roleplaying-sessions.md | 18 +- docs/source/Execute-Python-Code.md | 10 +- docs/source/First-Steps-Coding.md | 30 +- docs/source/Game-Planning.md | 12 +- docs/source/Gametime-Tutorial.md | 2 +- docs/source/Getting-Started.md | 74 +- docs/source/Glossary.md | 193 +- docs/source/Guest-Logins.md | 6 +- docs/source/Help-System-Tutorial.md | 2 +- docs/source/Help-System.md | 8 +- docs/source/How-To-Get-And-Give-Help.md | 6 +- .../How-to-connect-Evennia-to-Twitter.md | 8 +- docs/source/IRC.md | 2 +- .../source/Implementing-a-game-rule-system.md | 4 +- docs/source/Inputfuncs.md | 10 +- docs/source/Installing-on-Android.md | 6 +- docs/source/Internationalization.md | 2 +- docs/source/Links.md | 2 +- docs/source/Locks.md | 40 +- docs/source/Manually-Configuring-Color.md | 8 +- docs/source/Messagepath.md | 10 +- docs/source/MonitorHandler.md | 6 +- docs/source/NPC-shop-Tutorial.md | 16 +- docs/source/New-Models.md | 6 +- docs/source/Nicks.md | 8 +- docs/source/OOB.md | 10 +- docs/source/Objects.md | 32 +- docs/source/Online-Setup.md | 148 +- ...nd-arguments,-theory-and-best-practices.md | 4 +- docs/source/Portal-And-Server.md | 2 +- docs/source/Profiling.md | 2 +- docs/source/Python-basic-introduction.md | 16 +- docs/source/Python-basic-tutorial-part-two.md | 26 +- docs/source/Quirks.md | 4 +- docs/source/RSS.md | 2 +- docs/source/Running-Evennia-in-Docker.md | 2 +- docs/source/Screenshot.md | 2 +- docs/source/Scripts.md | 18 +- docs/source/Security.md | 2 +- docs/source/Server-Conf.md | 10 +- docs/source/Sessions.md | 20 +- docs/source/Signals.md | 2 +- docs/source/Soft-Code.md | 2 +- docs/source/Spawner-and-Prototypes.md | 18 +- docs/source/Start-Stop-Reload.md | 8 +- docs/source/Static-In-Game-Map.md | 24 +- docs/source/Tags.md | 14 +- docs/source/TextTags.md | 10 +- docs/source/TickerHandler.md | 6 +- docs/source/Turn-based-Combat-System.md | 20 +- docs/source/Tutorial-Aggressive-NPCs.md | 6 +- docs/source/Tutorial-NPCs-listening.md | 4 +- docs/source/Tutorial-Searching-For-Objects.md | 24 +- docs/source/Tutorial-Tweeting-Game-Stats.md | 4 +- docs/source/Tutorial-Vehicles.md | 12 +- docs/source/Tutorial-World-Introduction.md | 4 +- .../Tutorial-for-basic-MUSH-like-game.md | 30 +- docs/source/Tutorials.md | 106 +- docs/source/Typeclasses.md | 30 +- docs/source/Understanding-Color-Tags.md | 4 +- docs/source/Unit-Testing.md | 6 +- docs/source/Updating-Your-Game.md | 7 +- docs/source/Using-MUX-as-a-Standard.md | 2 +- docs/source/Using-Travis.md | 2 +- docs/source/Version-Control.md | 2 +- docs/source/Weather-Tutorial.md | 2 +- docs/source/Web-Character-Generation.md | 10 +- docs/source/Web-Character-View-Tutorial.md | 2 +- docs/source/Web-Features.md | 4 +- docs/source/Web-Tutorial.md | 8 +- docs/source/Wiki-Index.md | 280 +- docs/source/Zones.md | 4 +- .../api/{evennia-api.rst => evennia-api.md} | 3 + ...ounts.rst => evennia.accounts.accounts.md} | 3 + ...ts.admin.rst => evennia.accounts.admin.md} | 3 + ...unts.bots.rst => evennia.accounts.bots.md} | 3 + ...anager.rst => evennia.accounts.manager.md} | 3 + ...ennia.accounts.rst => evennia.accounts.md} | 3 + ....models.rst => evennia.accounts.models.md} | 3 + ...ler.rst => evennia.commands.cmdhandler.md} | 3 + ...rser.rst => evennia.commands.cmdparser.md} | 3 + ....cmdset.rst => evennia.commands.cmdset.md} | 3 + ....rst => evennia.commands.cmdsethandler.md} | 3 + ...ommand.rst => evennia.commands.command.md} | 3 + ...st => evennia.commands.default.account.md} | 3 + ....rst => evennia.commands.default.admin.md} | 3 + ... evennia.commands.default.batchprocess.md} | 3 + ...t => evennia.commands.default.building.md} | 3 + ...vennia.commands.default.cmdset_account.md} | 3 + ...nnia.commands.default.cmdset_character.md} | 3 + ...vennia.commands.default.cmdset_session.md} | 3 + ...nia.commands.default.cmdset_unloggedin.md} | 3 + ....rst => evennia.commands.default.comms.md} | 3 + ...st => evennia.commands.default.general.md} | 3 + ...p.rst => evennia.commands.default.help.md} | 3 + ...efault.rst => evennia.commands.default.md} | 3 + ...=> evennia.commands.default.muxcommand.md} | 3 + ...> evennia.commands.default.syscommands.md} | 3 + ...rst => evennia.commands.default.system.md} | 3 + ....rst => evennia.commands.default.tests.md} | 3 + ...=> evennia.commands.default.unloggedin.md} | 3 + ...ennia.commands.rst => evennia.commands.md} | 3 + ...comms.admin.rst => evennia.comms.admin.md} | 3 + ...er.rst => evennia.comms.channelhandler.md} | 3 + ...comms.comms.rst => evennia.comms.comms.md} | 3 + ...managers.rst => evennia.comms.managers.md} | 3 + .../{evennia.comms.rst => evennia.comms.md} | 3 + ...mms.models.rst => evennia.comms.models.md} | 3 + ...b.barter.rst => evennia.contrib.barter.md} | 3 + ...u.rst => evennia.contrib.building_menu.md} | 3 + ...chargen.rst => evennia.contrib.chargen.md} | 3 + ...othing.rst => evennia.contrib.clothing.md} | 3 + ...s.rst => evennia.contrib.color_markups.md} | 3 + ...rst => evennia.contrib.custom_gametime.md} | 3 + ...ntrib.dice.rst => evennia.contrib.dice.md} | 3 + ...gin.rst => evennia.contrib.email_login.md} | 3 + ...m.rst => evennia.contrib.extended_room.md} | 3 + ...dfill.rst => evennia.contrib.fieldfill.md} | 3 + ...ersub.rst => evennia.contrib.gendersub.md} | 3 + ..._bar.rst => evennia.contrib.health_bar.md} | 3 + ....contrib.ingame_python.callbackhandler.md} | 3 + ...evennia.contrib.ingame_python.commands.md} | 3 + ...ennia.contrib.ingame_python.eventfuncs.md} | 3 + ...n.rst => evennia.contrib.ingame_python.md} | 3 + ... evennia.contrib.ingame_python.scripts.md} | 3 + ...=> evennia.contrib.ingame_python.tests.md} | 3 + ...nnia.contrib.ingame_python.typeclasses.md} | 3 + ...=> evennia.contrib.ingame_python.utils.md} | 3 + ...ntrib.mail.rst => evennia.contrib.mail.md} | 3 + ...lder.rst => evennia.contrib.mapbuilder.md} | 3 + ...evennia.contrib.rst => evennia.contrib.md} | 3 + ...ogin.rst => evennia.contrib.menu_login.md} | 3 + ...cer.rst => evennia.contrib.multidescer.md} | 3 + ...puzzles.rst => evennia.contrib.puzzles.md} | 3 + ...vennia.contrib.random_string_generator.md} | 3 + ...uage.rst => evennia.contrib.rplanguage.md} | 3 + ...system.rst => evennia.contrib.rpsystem.md} | 3 + ...t => evennia.contrib.security.auditing.md} | 3 + ...nnia.contrib.security.auditing.outputs.md} | 3 + ...ennia.contrib.security.auditing.server.md} | 3 + ...vennia.contrib.security.auditing.tests.md} | 3 + ...curity.rst => evennia.contrib.security.md} | 3 + ...door.rst => evennia.contrib.simpledoor.md} | 3 + ..._exit.rst => evennia.contrib.slow_exit.md} | 3 + ...npc.rst => evennia.contrib.talking_npc.md} | 3 + ...ect.rst => evennia.contrib.tree_select.md} | 3 + ...ttle.rst => evennia.contrib.turnbattle.md} | 3 + ...=> evennia.contrib.turnbattle.tb_basic.md} | 3 + ...=> evennia.contrib.turnbattle.tb_equip.md} | 3 + ...=> evennia.contrib.turnbattle.tb_items.md} | 3 + ...=> evennia.contrib.turnbattle.tb_magic.md} | 3 + ...=> evennia.contrib.turnbattle.tb_range.md} | 3 + ...ontrib.tutorial_examples.bodyfunctions.md} | 3 + ...ib.tutorial_examples.cmdset_red_button.md} | 3 + ...b.tutorial_examples.example_batch_code.md} | 3 + ...t => evennia.contrib.tutorial_examples.md} | 3 + ...a.contrib.tutorial_examples.red_button.md} | 3 + ...b.tutorial_examples.red_button_scripts.md} | 3 + ...vennia.contrib.tutorial_examples.tests.md} | 3 + ...nnia.contrib.tutorial_world.intro_menu.md} | 3 + ....rst => evennia.contrib.tutorial_world.md} | 3 + ... => evennia.contrib.tutorial_world.mob.md} | 3 + ...evennia.contrib.tutorial_world.objects.md} | 3 + ...> evennia.contrib.tutorial_world.rooms.md} | 3 + ...and.rst => evennia.contrib.unixcommand.md} | 3 + ...ness.rst => evennia.contrib.wilderness.md} | 3 + ...a.help.admin.rst => evennia.help.admin.md} | 3 + ...lp.manager.rst => evennia.help.manager.md} | 3 + .../api/{evennia.help.rst => evennia.help.md} | 3 + ...help.models.rst => evennia.help.models.md} | 3 + ...ckfuncs.rst => evennia.locks.lockfuncs.md} | 3 + ...ndler.rst => evennia.locks.lockhandler.md} | 3 + .../{evennia.locks.rst => evennia.locks.md} | 3 + docs/source/api/{evennia.rst => evennia.md} | 3 + ...cts.admin.rst => evennia.objects.admin.md} | 3 + ...manager.rst => evennia.objects.manager.md} | 3 + ...evennia.objects.rst => evennia.objects.md} | 3 + ...s.models.rst => evennia.objects.models.md} | 3 + ...objects.rst => evennia.objects.objects.md} | 3 + ...a.prototypes.rst => evennia.prototypes.md} | 3 + ....menus.rst => evennia.prototypes.menus.md} | 3 + ...cs.rst => evennia.prototypes.protfuncs.md} | 3 + ...s.rst => evennia.prototypes.prototypes.md} | 3 + ...wner.rst => evennia.prototypes.spawner.md} | 3 + ...pts.admin.rst => evennia.scripts.admin.md} | 3 + ...manager.rst => evennia.scripts.manager.md} | 3 + ...evennia.scripts.rst => evennia.scripts.md} | 3 + ...s.models.rst => evennia.scripts.models.md} | 3 + ....rst => evennia.scripts.monitorhandler.md} | 3 + ...r.rst => evennia.scripts.scripthandler.md} | 3 + ...scripts.rst => evennia.scripts.scripts.md} | 3 + ...ler.rst => evennia.scripts.taskhandler.md} | 3 + ...r.rst => evennia.scripts.tickerhandler.md} | 3 + ...rver.admin.rst => evennia.server.admin.md} | 3 + ...lient.rst => evennia.server.amp_client.md} | 3 + ...st => evennia.server.connection_wizard.md} | 3 + ...ons.rst => evennia.server.deprecations.md} | 3 + ...rst => evennia.server.evennia_launcher.md} | 3 + ...vennia.server.game_index_client.client.md} | 3 + ...st => evennia.server.game_index_client.md} | 3 + ...ennia.server.game_index_client.service.md} | 3 + ...up.rst => evennia.server.initial_setup.md} | 3 + ...funcs.rst => evennia.server.inputfuncs.md} | 3 + ....manager.rst => evennia.server.manager.md} | 3 + .../{evennia.server.rst => evennia.server.md} | 3 + ...er.models.rst => evennia.server.models.md} | 3 + ...l.amp.rst => evennia.server.portal.amp.md} | 3 + ...st => evennia.server.portal.amp_server.md} | 3 + ...rst => evennia.server.portal.grapevine.md} | 3 + ...l.irc.rst => evennia.server.portal.irc.md} | 3 + ...mccp.rst => evennia.server.portal.mccp.md} | 3 + ...er.portal.rst => evennia.server.portal.md} | 3 + ...mssp.rst => evennia.server.portal.mssp.md} | 3 + ...l.mxp.rst => evennia.server.portal.mxp.md} | 3 + ...naws.rst => evennia.server.portal.naws.md} | 3 + ...al.rst => evennia.server.portal.portal.md} | 3 + ...nia.server.portal.portalsessionhandler.md} | 3 + ...l.rss.rst => evennia.server.portal.rss.md} | 3 + ...l.ssh.rst => evennia.server.portal.ssh.md} | 3 + ...l.ssl.rst => evennia.server.portal.ssl.md} | 3 + ...t => evennia.server.portal.suppress_ga.md} | 3 + ...et.rst => evennia.server.portal.telnet.md} | 3 + ...st => evennia.server.portal.telnet_oob.md} | 3 + ...st => evennia.server.portal.telnet_ssl.md} | 3 + ...sts.rst => evennia.server.portal.tests.md} | 3 + ...ype.rst => evennia.server.portal.ttype.md} | 3 + ...rst => evennia.server.portal.webclient.md} | 3 + ...> evennia.server.portal.webclient_ajax.md} | 3 + ...> evennia.server.profiling.dummyrunner.md} | 3 + ....server.profiling.dummyrunner_settings.md} | 3 + ...filing.rst => evennia.server.profiling.md} | 3 + ...st => evennia.server.profiling.memplot.md} | 3 + ...vennia.server.profiling.settings_mixin.md} | 3 + ... evennia.server.profiling.test_queries.md} | 3 + ....rst => evennia.server.profiling.tests.md} | 3 + ... => evennia.server.profiling.timetrace.md} | 3 + ...er.server.rst => evennia.server.server.md} | 3 + ...on.rst => evennia.server.serversession.md} | 3 + ....session.rst => evennia.server.session.md} | 3 + ...r.rst => evennia.server.sessionhandler.md} | 3 + ....signals.rst => evennia.server.signals.md} | 3 + ...hrottle.rst => evennia.server.throttle.md} | 3 + ...ators.rst => evennia.server.validators.md} | 3 + ...server.rst => evennia.server.webserver.md} | 3 + ...efault.rst => evennia.settings_default.md} | 3 + ...admin.rst => evennia.typeclasses.admin.md} | 3 + ....rst => evennia.typeclasses.attributes.md} | 3 + ...rs.rst => evennia.typeclasses.managers.md} | 3 + ...typeclasses.rst => evennia.typeclasses.md} | 3 + ...dels.rst => evennia.typeclasses.models.md} | 3 + ...s.tags.rst => evennia.typeclasses.tags.md} | 3 + ...a.utils.ansi.rst => evennia.utils.ansi.md} | 3 + ...s.rst => evennia.utils.batchprocessors.md} | 3 + ...ainers.rst => evennia.utils.containers.md} | 3 + ...ils.create.rst => evennia.utils.create.md} | 3 + ...alize.rst => evennia.utils.dbserialize.md} | 3 + ...eveditor.rst => evennia.utils.eveditor.md} | 3 + ...ils.evform.rst => evennia.utils.evform.md} | 3 + ...ils.evmenu.rst => evennia.utils.evmenu.md} | 3 + ...ils.evmore.rst => evennia.utils.evmore.md} | 3 + ...s.evtable.rst => evennia.utils.evtable.md} | 3 + ...gametime.rst => evennia.utils.gametime.md} | 3 + ....rst => evennia.utils.idmapper.manager.md} | 3 + ...idmapper.rst => evennia.utils.idmapper.md} | 3 + ...s.rst => evennia.utils.idmapper.models.md} | 3 + ...ts.rst => evennia.utils.idmapper.tests.md} | 3 + ...funcs.rst => evennia.utils.inlinefuncs.md} | 3 + ...ils.logger.rst => evennia.utils.logger.md} | 3 + .../{evennia.utils.rst => evennia.utils.md} | 3 + ...ses.rst => evennia.utils.optionclasses.md} | 3 + ...ler.rst => evennia.utils.optionhandler.md} | 3 + ...field.rst => evennia.utils.picklefield.md} | 3 + ...ils.search.rst => evennia.utils.search.md} | 3 + ...es.rst => evennia.utils.test_resources.md} | 3 + ...xt2html.rst => evennia.utils.text2html.md} | 3 + ...utils.utils.rst => evennia.utils.utils.md} | 3 + ...cs.rst => evennia.utils.validatorfuncs.md} | 3 + .../api/{evennia.web.rst => evennia.web.md} | 3 + ...ennia.web.urls.rst => evennia.web.urls.md} | 3 + ...ends.rst => evennia.web.utils.backends.md} | 3 + ...t => evennia.web.utils.general_context.md} | 3 + ...nia.web.utils.rst => evennia.web.utils.md} | 3 + ...re.rst => evennia.web.utils.middleware.md} | 3 + ...s.tests.rst => evennia.web.utils.tests.md} | 3 + ...webclient.rst => evennia.web.webclient.md} | 3 + ...urls.rst => evennia.web.webclient.urls.md} | 3 + ...ews.rst => evennia.web.webclient.views.md} | 3 + ...forms.rst => evennia.web.website.forms.md} | 3 + ...web.website.rst => evennia.web.website.md} | 3 + ...nnia.web.website.templatetags.addclass.md} | 3 + ...st => evennia.web.website.templatetags.md} | 3 + ...tests.rst => evennia.web.website.tests.md} | 3 + ...e.urls.rst => evennia.web.website.urls.md} | 3 + ...views.rst => evennia.web.website.views.md} | 3 + docs/source/conf.py | 151 +- docs/source/index.md | 48 +- docs/source/toc.md | 513 +++- evennia/accounts/accounts.py | 2 +- evennia/accounts/manager.py | 2 +- evennia/commands/default/system.py | 2 + evennia/commands/default/unloggedin.py | 3 + evennia/objects/manager.py | 2 +- evennia/scripts/manager.py | 2 +- evennia/utils/search.py | 1 + 359 files changed, 3275 insertions(+), 4567 deletions(-) create mode 100755 docs/pylib/api_rst2md.py create mode 100644 docs/pylib/fmtwidth.py create mode 100644 docs/pylib/update_default_cmd_index.py delete mode 100644 docs/source/Default-Command-Help.md create mode 100644 docs/source/Default-Commands.md rename docs/source/api/{evennia-api.rst => evennia-api.md} (76%) rename docs/source/api/{evennia.accounts.accounts.rst => evennia.accounts.accounts.md} (89%) rename docs/source/api/{evennia.accounts.admin.rst => evennia.accounts.admin.md} (89%) rename docs/source/api/{evennia.accounts.bots.rst => evennia.accounts.bots.md} (88%) rename docs/source/api/{evennia.accounts.manager.rst => evennia.accounts.manager.md} (89%) rename docs/source/api/{evennia.accounts.rst => evennia.accounts.md} (94%) rename docs/source/api/{evennia.accounts.models.rst => evennia.accounts.models.md} (89%) rename docs/source/api/{evennia.commands.cmdhandler.rst => evennia.commands.cmdhandler.md} (90%) rename docs/source/api/{evennia.commands.cmdparser.rst => evennia.commands.cmdparser.md} (89%) rename docs/source/api/{evennia.commands.cmdset.rst => evennia.commands.cmdset.md} (89%) rename docs/source/api/{evennia.commands.cmdsethandler.rst => evennia.commands.cmdsethandler.md} (90%) rename docs/source/api/{evennia.commands.command.rst => evennia.commands.command.md} (89%) rename docs/source/api/{evennia.commands.default.account.rst => evennia.commands.default.account.md} (90%) rename docs/source/api/{evennia.commands.default.admin.rst => evennia.commands.default.admin.md} (90%) rename docs/source/api/{evennia.commands.default.batchprocess.rst => evennia.commands.default.batchprocess.md} (91%) rename docs/source/api/{evennia.commands.default.building.rst => evennia.commands.default.building.md} (90%) rename docs/source/api/{evennia.commands.default.cmdset_account.rst => evennia.commands.default.cmdset_account.md} (91%) rename docs/source/api/{evennia.commands.default.cmdset_character.rst => evennia.commands.default.cmdset_character.md} (92%) rename docs/source/api/{evennia.commands.default.cmdset_session.rst => evennia.commands.default.cmdset_session.md} (91%) rename docs/source/api/{evennia.commands.default.cmdset_unloggedin.rst => evennia.commands.default.cmdset_unloggedin.md} (92%) rename docs/source/api/{evennia.commands.default.comms.rst => evennia.commands.default.comms.md} (90%) rename docs/source/api/{evennia.commands.default.general.rst => evennia.commands.default.general.md} (90%) rename docs/source/api/{evennia.commands.default.help.rst => evennia.commands.default.help.md} (90%) rename docs/source/api/{evennia.commands.default.rst => evennia.commands.default.md} (97%) rename docs/source/api/{evennia.commands.default.muxcommand.rst => evennia.commands.default.muxcommand.md} (91%) rename docs/source/api/{evennia.commands.default.syscommands.rst => evennia.commands.default.syscommands.md} (91%) rename docs/source/api/{evennia.commands.default.system.rst => evennia.commands.default.system.md} (90%) rename docs/source/api/{evennia.commands.default.tests.rst => evennia.commands.default.tests.md} (90%) rename docs/source/api/{evennia.commands.default.unloggedin.rst => evennia.commands.default.unloggedin.md} (91%) rename docs/source/api/{evennia.commands.rst => evennia.commands.md} (95%) rename docs/source/api/{evennia.comms.admin.rst => evennia.comms.admin.md} (88%) rename docs/source/api/{evennia.comms.channelhandler.rst => evennia.comms.channelhandler.md} (90%) rename docs/source/api/{evennia.comms.comms.rst => evennia.comms.comms.md} (88%) rename docs/source/api/{evennia.comms.managers.rst => evennia.comms.managers.md} (89%) rename docs/source/api/{evennia.comms.rst => evennia.comms.md} (94%) rename docs/source/api/{evennia.comms.models.rst => evennia.comms.models.md} (88%) rename docs/source/api/{evennia.contrib.barter.rst => evennia.contrib.barter.md} (89%) rename docs/source/api/{evennia.contrib.building_menu.rst => evennia.contrib.building_menu.md} (90%) rename docs/source/api/{evennia.contrib.chargen.rst => evennia.contrib.chargen.md} (89%) rename docs/source/api/{evennia.contrib.clothing.rst => evennia.contrib.clothing.md} (89%) rename docs/source/api/{evennia.contrib.color_markups.rst => evennia.contrib.color_markups.md} (90%) rename docs/source/api/{evennia.contrib.custom_gametime.rst => evennia.contrib.custom_gametime.md} (90%) rename docs/source/api/{evennia.contrib.dice.rst => evennia.contrib.dice.md} (88%) rename docs/source/api/{evennia.contrib.email_login.rst => evennia.contrib.email_login.md} (90%) rename docs/source/api/{evennia.contrib.extended_room.rst => evennia.contrib.extended_room.md} (90%) rename docs/source/api/{evennia.contrib.fieldfill.rst => evennia.contrib.fieldfill.md} (89%) rename docs/source/api/{evennia.contrib.gendersub.rst => evennia.contrib.gendersub.md} (89%) rename docs/source/api/{evennia.contrib.health_bar.rst => evennia.contrib.health_bar.md} (90%) rename docs/source/api/{evennia.contrib.ingame_python.callbackhandler.rst => evennia.contrib.ingame_python.callbackhandler.md} (92%) rename docs/source/api/{evennia.contrib.ingame_python.commands.rst => evennia.contrib.ingame_python.commands.md} (91%) rename docs/source/api/{evennia.contrib.ingame_python.eventfuncs.rst => evennia.contrib.ingame_python.eventfuncs.md} (91%) rename docs/source/api/{evennia.contrib.ingame_python.rst => evennia.contrib.ingame_python.md} (96%) rename docs/source/api/{evennia.contrib.ingame_python.scripts.rst => evennia.contrib.ingame_python.scripts.md} (91%) rename docs/source/api/{evennia.contrib.ingame_python.tests.rst => evennia.contrib.ingame_python.tests.md} (91%) rename docs/source/api/{evennia.contrib.ingame_python.typeclasses.rst => evennia.contrib.ingame_python.typeclasses.md} (92%) rename docs/source/api/{evennia.contrib.ingame_python.utils.rst => evennia.contrib.ingame_python.utils.md} (91%) rename docs/source/api/{evennia.contrib.mail.rst => evennia.contrib.mail.md} (88%) rename docs/source/api/{evennia.contrib.mapbuilder.rst => evennia.contrib.mapbuilder.md} (89%) rename docs/source/api/{evennia.contrib.rst => evennia.contrib.md} (98%) rename docs/source/api/{evennia.contrib.menu_login.rst => evennia.contrib.menu_login.md} (90%) rename docs/source/api/{evennia.contrib.multidescer.rst => evennia.contrib.multidescer.md} (90%) rename docs/source/api/{evennia.contrib.puzzles.rst => evennia.contrib.puzzles.md} (89%) rename docs/source/api/{evennia.contrib.random_string_generator.rst => evennia.contrib.random_string_generator.md} (91%) rename docs/source/api/{evennia.contrib.rplanguage.rst => evennia.contrib.rplanguage.md} (89%) rename docs/source/api/{evennia.contrib.rpsystem.rst => evennia.contrib.rpsystem.md} (89%) rename docs/source/api/{evennia.contrib.security.auditing.rst => evennia.contrib.security.auditing.md} (95%) rename docs/source/api/{evennia.contrib.security.auditing.outputs.rst => evennia.contrib.security.auditing.outputs.md} (91%) rename docs/source/api/{evennia.contrib.security.auditing.server.rst => evennia.contrib.security.auditing.server.md} (91%) rename docs/source/api/{evennia.contrib.security.auditing.tests.rst => evennia.contrib.security.auditing.tests.md} (91%) rename docs/source/api/{evennia.contrib.security.rst => evennia.contrib.security.md} (92%) rename docs/source/api/{evennia.contrib.simpledoor.rst => evennia.contrib.simpledoor.md} (89%) rename docs/source/api/{evennia.contrib.slow_exit.rst => evennia.contrib.slow_exit.md} (89%) rename docs/source/api/{evennia.contrib.talking_npc.rst => evennia.contrib.talking_npc.md} (90%) rename docs/source/api/{evennia.contrib.tree_select.rst => evennia.contrib.tree_select.md} (90%) rename docs/source/api/{evennia.contrib.turnbattle.rst => evennia.contrib.turnbattle.md} (95%) rename docs/source/api/{evennia.contrib.turnbattle.tb_basic.rst => evennia.contrib.turnbattle.tb_basic.md} (91%) rename docs/source/api/{evennia.contrib.turnbattle.tb_equip.rst => evennia.contrib.turnbattle.tb_equip.md} (91%) rename docs/source/api/{evennia.contrib.turnbattle.tb_items.rst => evennia.contrib.turnbattle.tb_items.md} (91%) rename docs/source/api/{evennia.contrib.turnbattle.tb_magic.rst => evennia.contrib.turnbattle.tb_magic.md} (91%) rename docs/source/api/{evennia.contrib.turnbattle.tb_range.rst => evennia.contrib.turnbattle.tb_range.md} (91%) rename docs/source/api/{evennia.contrib.tutorial_examples.bodyfunctions.rst => evennia.contrib.tutorial_examples.bodyfunctions.md} (92%) rename docs/source/api/{evennia.contrib.tutorial_examples.cmdset_red_button.rst => evennia.contrib.tutorial_examples.cmdset_red_button.md} (93%) rename docs/source/api/{evennia.contrib.tutorial_examples.example_batch_code.rst => evennia.contrib.tutorial_examples.example_batch_code.md} (93%) rename docs/source/api/{evennia.contrib.tutorial_examples.rst => evennia.contrib.tutorial_examples.md} (96%) rename docs/source/api/{evennia.contrib.tutorial_examples.red_button.rst => evennia.contrib.tutorial_examples.red_button.md} (92%) rename docs/source/api/{evennia.contrib.tutorial_examples.red_button_scripts.rst => evennia.contrib.tutorial_examples.red_button_scripts.md} (93%) rename docs/source/api/{evennia.contrib.tutorial_examples.tests.rst => evennia.contrib.tutorial_examples.tests.md} (91%) rename docs/source/api/{evennia.contrib.tutorial_world.intro_menu.rst => evennia.contrib.tutorial_world.intro_menu.md} (92%) rename docs/source/api/{evennia.contrib.tutorial_world.rst => evennia.contrib.tutorial_world.md} (95%) rename docs/source/api/{evennia.contrib.tutorial_world.mob.rst => evennia.contrib.tutorial_world.mob.md} (91%) rename docs/source/api/{evennia.contrib.tutorial_world.objects.rst => evennia.contrib.tutorial_world.objects.md} (91%) rename docs/source/api/{evennia.contrib.tutorial_world.rooms.rst => evennia.contrib.tutorial_world.rooms.md} (91%) rename docs/source/api/{evennia.contrib.unixcommand.rst => evennia.contrib.unixcommand.md} (90%) rename docs/source/api/{evennia.contrib.wilderness.rst => evennia.contrib.wilderness.md} (89%) rename docs/source/api/{evennia.help.admin.rst => evennia.help.admin.md} (88%) rename docs/source/api/{evennia.help.manager.rst => evennia.help.manager.md} (88%) rename docs/source/api/{evennia.help.rst => evennia.help.md} (92%) rename docs/source/api/{evennia.help.models.rst => evennia.help.models.md} (88%) rename docs/source/api/{evennia.locks.lockfuncs.rst => evennia.locks.lockfuncs.md} (89%) rename docs/source/api/{evennia.locks.lockhandler.rst => evennia.locks.lockhandler.md} (89%) rename docs/source/api/{evennia.locks.rst => evennia.locks.md} (92%) rename docs/source/api/{evennia.rst => evennia.md} (96%) rename docs/source/api/{evennia.objects.admin.rst => evennia.objects.admin.md} (88%) rename docs/source/api/{evennia.objects.manager.rst => evennia.objects.manager.md} (89%) rename docs/source/api/{evennia.objects.rst => evennia.objects.md} (93%) rename docs/source/api/{evennia.objects.models.rst => evennia.objects.models.md} (89%) rename docs/source/api/{evennia.objects.objects.rst => evennia.objects.objects.md} (89%) rename docs/source/api/{evennia.prototypes.rst => evennia.prototypes.md} (94%) rename docs/source/api/{evennia.prototypes.menus.rst => evennia.prototypes.menus.md} (89%) rename docs/source/api/{evennia.prototypes.protfuncs.rst => evennia.prototypes.protfuncs.md} (90%) rename docs/source/api/{evennia.prototypes.prototypes.rst => evennia.prototypes.prototypes.md} (90%) rename docs/source/api/{evennia.prototypes.spawner.rst => evennia.prototypes.spawner.md} (89%) rename docs/source/api/{evennia.scripts.admin.rst => evennia.scripts.admin.md} (88%) rename docs/source/api/{evennia.scripts.manager.rst => evennia.scripts.manager.md} (89%) rename docs/source/api/{evennia.scripts.rst => evennia.scripts.md} (95%) rename docs/source/api/{evennia.scripts.models.rst => evennia.scripts.models.md} (89%) rename docs/source/api/{evennia.scripts.monitorhandler.rst => evennia.scripts.monitorhandler.md} (90%) rename docs/source/api/{evennia.scripts.scripthandler.rst => evennia.scripts.scripthandler.md} (90%) rename docs/source/api/{evennia.scripts.scripts.rst => evennia.scripts.scripts.md} (89%) rename docs/source/api/{evennia.scripts.taskhandler.rst => evennia.scripts.taskhandler.md} (90%) rename docs/source/api/{evennia.scripts.tickerhandler.rst => evennia.scripts.tickerhandler.md} (90%) rename docs/source/api/{evennia.server.admin.rst => evennia.server.admin.md} (88%) rename docs/source/api/{evennia.server.amp_client.rst => evennia.server.amp_client.md} (89%) rename docs/source/api/{evennia.server.connection_wizard.rst => evennia.server.connection_wizard.md} (90%) rename docs/source/api/{evennia.server.deprecations.rst => evennia.server.deprecations.md} (90%) rename docs/source/api/{evennia.server.evennia_launcher.rst => evennia.server.evennia_launcher.md} (90%) rename docs/source/api/{evennia.server.game_index_client.client.rst => evennia.server.game_index_client.client.md} (91%) rename docs/source/api/{evennia.server.game_index_client.rst => evennia.server.game_index_client.md} (94%) rename docs/source/api/{evennia.server.game_index_client.service.rst => evennia.server.game_index_client.service.md} (91%) rename docs/source/api/{evennia.server.initial_setup.rst => evennia.server.initial_setup.md} (90%) rename docs/source/api/{evennia.server.inputfuncs.rst => evennia.server.inputfuncs.md} (89%) rename docs/source/api/{evennia.server.manager.rst => evennia.server.manager.md} (89%) rename docs/source/api/{evennia.server.rst => evennia.server.md} (97%) rename docs/source/api/{evennia.server.models.rst => evennia.server.models.md} (88%) rename docs/source/api/{evennia.server.portal.amp.rst => evennia.server.portal.amp.md} (89%) rename docs/source/api/{evennia.server.portal.amp_server.rst => evennia.server.portal.amp_server.md} (90%) rename docs/source/api/{evennia.server.portal.grapevine.rst => evennia.server.portal.grapevine.md} (90%) rename docs/source/api/{evennia.server.portal.irc.rst => evennia.server.portal.irc.md} (89%) rename docs/source/api/{evennia.server.portal.mccp.rst => evennia.server.portal.mccp.md} (89%) rename docs/source/api/{evennia.server.portal.rst => evennia.server.portal.md} (97%) rename docs/source/api/{evennia.server.portal.mssp.rst => evennia.server.portal.mssp.md} (89%) rename docs/source/api/{evennia.server.portal.mxp.rst => evennia.server.portal.mxp.md} (89%) rename docs/source/api/{evennia.server.portal.naws.rst => evennia.server.portal.naws.md} (89%) rename docs/source/api/{evennia.server.portal.portal.rst => evennia.server.portal.portal.md} (90%) rename docs/source/api/{evennia.server.portal.portalsessionhandler.rst => evennia.server.portal.portalsessionhandler.md} (92%) rename docs/source/api/{evennia.server.portal.rss.rst => evennia.server.portal.rss.md} (89%) rename docs/source/api/{evennia.server.portal.ssh.rst => evennia.server.portal.ssh.md} (89%) rename docs/source/api/{evennia.server.portal.ssl.rst => evennia.server.portal.ssl.md} (89%) rename docs/source/api/{evennia.server.portal.suppress_ga.rst => evennia.server.portal.suppress_ga.md} (91%) rename docs/source/api/{evennia.server.portal.telnet.rst => evennia.server.portal.telnet.md} (90%) rename docs/source/api/{evennia.server.portal.telnet_oob.rst => evennia.server.portal.telnet_oob.md} (90%) rename docs/source/api/{evennia.server.portal.telnet_ssl.rst => evennia.server.portal.telnet_ssl.md} (90%) rename docs/source/api/{evennia.server.portal.tests.rst => evennia.server.portal.tests.md} (90%) rename docs/source/api/{evennia.server.portal.ttype.rst => evennia.server.portal.ttype.md} (90%) rename docs/source/api/{evennia.server.portal.webclient.rst => evennia.server.portal.webclient.md} (90%) rename docs/source/api/{evennia.server.portal.webclient_ajax.rst => evennia.server.portal.webclient_ajax.md} (91%) rename docs/source/api/{evennia.server.profiling.dummyrunner.rst => evennia.server.profiling.dummyrunner.md} (91%) rename docs/source/api/{evennia.server.profiling.dummyrunner_settings.rst => evennia.server.profiling.dummyrunner_settings.md} (92%) rename docs/source/api/{evennia.server.profiling.rst => evennia.server.profiling.md} (96%) rename docs/source/api/{evennia.server.profiling.memplot.rst => evennia.server.profiling.memplot.md} (90%) rename docs/source/api/{evennia.server.profiling.settings_mixin.rst => evennia.server.profiling.settings_mixin.md} (91%) rename docs/source/api/{evennia.server.profiling.test_queries.rst => evennia.server.profiling.test_queries.md} (91%) rename docs/source/api/{evennia.server.profiling.tests.rst => evennia.server.profiling.tests.md} (90%) rename docs/source/api/{evennia.server.profiling.timetrace.rst => evennia.server.profiling.timetrace.md} (91%) rename docs/source/api/{evennia.server.server.rst => evennia.server.server.md} (88%) rename docs/source/api/{evennia.server.serversession.rst => evennia.server.serversession.md} (90%) rename docs/source/api/{evennia.server.session.rst => evennia.server.session.md} (89%) rename docs/source/api/{evennia.server.sessionhandler.rst => evennia.server.sessionhandler.md} (90%) rename docs/source/api/{evennia.server.signals.rst => evennia.server.signals.md} (89%) rename docs/source/api/{evennia.server.throttle.rst => evennia.server.throttle.md} (89%) rename docs/source/api/{evennia.server.validators.rst => evennia.server.validators.md} (89%) rename docs/source/api/{evennia.server.webserver.rst => evennia.server.webserver.md} (89%) rename docs/source/api/{evennia.settings_default.rst => evennia.settings_default.md} (89%) rename docs/source/api/{evennia.typeclasses.admin.rst => evennia.typeclasses.admin.md} (89%) rename docs/source/api/{evennia.typeclasses.attributes.rst => evennia.typeclasses.attributes.md} (90%) rename docs/source/api/{evennia.typeclasses.managers.rst => evennia.typeclasses.managers.md} (90%) rename docs/source/api/{evennia.typeclasses.rst => evennia.typeclasses.md} (94%) rename docs/source/api/{evennia.typeclasses.models.rst => evennia.typeclasses.models.md} (89%) rename docs/source/api/{evennia.typeclasses.tags.rst => evennia.typeclasses.tags.md} (89%) rename docs/source/api/{evennia.utils.ansi.rst => evennia.utils.ansi.md} (88%) rename docs/source/api/{evennia.utils.batchprocessors.rst => evennia.utils.batchprocessors.md} (90%) rename docs/source/api/{evennia.utils.containers.rst => evennia.utils.containers.md} (89%) rename docs/source/api/{evennia.utils.create.rst => evennia.utils.create.md} (88%) rename docs/source/api/{evennia.utils.dbserialize.rst => evennia.utils.dbserialize.md} (89%) rename docs/source/api/{evennia.utils.eveditor.rst => evennia.utils.eveditor.md} (89%) rename docs/source/api/{evennia.utils.evform.rst => evennia.utils.evform.md} (88%) rename docs/source/api/{evennia.utils.evmenu.rst => evennia.utils.evmenu.md} (88%) rename docs/source/api/{evennia.utils.evmore.rst => evennia.utils.evmore.md} (88%) rename docs/source/api/{evennia.utils.evtable.rst => evennia.utils.evtable.md} (88%) rename docs/source/api/{evennia.utils.gametime.rst => evennia.utils.gametime.md} (89%) rename docs/source/api/{evennia.utils.idmapper.manager.rst => evennia.utils.idmapper.manager.md} (90%) rename docs/source/api/{evennia.utils.idmapper.rst => evennia.utils.idmapper.md} (93%) rename docs/source/api/{evennia.utils.idmapper.models.rst => evennia.utils.idmapper.models.md} (90%) rename docs/source/api/{evennia.utils.idmapper.tests.rst => evennia.utils.idmapper.tests.md} (90%) rename docs/source/api/{evennia.utils.inlinefuncs.rst => evennia.utils.inlinefuncs.md} (89%) rename docs/source/api/{evennia.utils.logger.rst => evennia.utils.logger.md} (88%) rename docs/source/api/{evennia.utils.rst => evennia.utils.md} (97%) rename docs/source/api/{evennia.utils.optionclasses.rst => evennia.utils.optionclasses.md} (90%) rename docs/source/api/{evennia.utils.optionhandler.rst => evennia.utils.optionhandler.md} (90%) rename docs/source/api/{evennia.utils.picklefield.rst => evennia.utils.picklefield.md} (89%) rename docs/source/api/{evennia.utils.search.rst => evennia.utils.search.md} (88%) rename docs/source/api/{evennia.utils.test_resources.rst => evennia.utils.test_resources.md} (90%) rename docs/source/api/{evennia.utils.text2html.rst => evennia.utils.text2html.md} (89%) rename docs/source/api/{evennia.utils.utils.rst => evennia.utils.utils.md} (88%) rename docs/source/api/{evennia.utils.validatorfuncs.rst => evennia.utils.validatorfuncs.md} (90%) rename docs/source/api/{evennia.web.rst => evennia.web.md} (93%) rename docs/source/api/{evennia.web.urls.rst => evennia.web.urls.md} (87%) rename docs/source/api/{evennia.web.utils.backends.rst => evennia.web.utils.backends.md} (89%) rename docs/source/api/{evennia.web.utils.general_context.rst => evennia.web.utils.general_context.md} (91%) rename docs/source/api/{evennia.web.utils.rst => evennia.web.utils.md} (94%) rename docs/source/api/{evennia.web.utils.middleware.rst => evennia.web.utils.middleware.md} (90%) rename docs/source/api/{evennia.web.utils.tests.rst => evennia.web.utils.tests.md} (89%) rename docs/source/api/{evennia.web.webclient.rst => evennia.web.webclient.md} (93%) rename docs/source/api/{evennia.web.webclient.urls.rst => evennia.web.webclient.urls.md} (89%) rename docs/source/api/{evennia.web.webclient.views.rst => evennia.web.webclient.views.md} (90%) rename docs/source/api/{evennia.web.website.forms.rst => evennia.web.website.forms.md} (89%) rename docs/source/api/{evennia.web.website.rst => evennia.web.website.md} (95%) rename docs/source/api/{evennia.web.website.templatetags.addclass.rst => evennia.web.website.templatetags.addclass.md} (91%) rename docs/source/api/{evennia.web.website.templatetags.rst => evennia.web.website.templatetags.md} (93%) rename docs/source/api/{evennia.web.website.tests.rst => evennia.web.website.tests.md} (89%) rename docs/source/api/{evennia.web.website.urls.rst => evennia.web.website.urls.md} (89%) rename docs/source/api/{evennia.web.website.views.rst => evennia.web.website.views.md} (89%) diff --git a/docs/Makefile b/docs/Makefile index 0cc01b83ed..0493d9760c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -11,6 +11,7 @@ SPHINXBUILD ?= sphinx-build SPHINXMULTIVERSION ?= sphinx-multiversion SPHINXAPIDOC ?= sphinx-apidoc SPHINXAPIDOCOPTS = --tocfile evennia-api --module-first --force -d 6 --separate --templatedir=$(SOURCEDIR)/_templates/ +SPHINXAPIDOCOPTSQUICK = --tocfile evennia-api --module-first -d 6 --separate --templatedir=$(SOURCEDIR)/_templates/ SPHINXAPIDOCENV = members,undoc-members,show-inheritance SPHINXAPIDOCEXCLUDE = ../*/migrations/* ../evennia/game_template/* ../evennia/*/tests/* ../evennia/*/tests.py @@ -28,9 +29,12 @@ QUICKFILES= help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @echo "Evennia-specific: " - @echo " $(cblue)install$(cnorm) to get build requirements" + @echo " $(cblue)install$(cnorm) to get doc build requirements" @echo " $(cblue)clean$(cnorm) to remove remnants of a previous build" + @echo " $(cblue)quick$(cnorm) to build local docs but skip the autodocs (for quick testing)" + @echo " $(cblue)quickstrict$(cnorm) to build like 'quick' but abort immediately on any error" @echo " $(cblue)local$(cnorm) to build local html docs of the current branch (no multiversion)." + @echo " $(cblue)localupdate$(cnorm) to build local html docs (only update changes) @echo " $(cblue)mv-local$(cnorm) to build multiversion html docs, without deploying (req: local git commit first)" @echo " $(cblue)deploy$(cnorm) to deploy previously built multiversion docs online (req: commit and github push access)" @echo " $(cblue)release$(cnorm) to build + deploy multiversion docs online (req: commit and github push access)" @@ -66,6 +70,10 @@ _autodoc-index: make _clean_api_index @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) SPHINX_APIDOC_OPTIONS=$(SPHINXAPIDOCENV) $(SPHINXAPIDOC) $(SPHINXAPIDOCOPTS) -o $(SOURCEDIR)/api/ $(EVDIR) $(SPHINXAPIDOCEXCLUDE) make _reformat_apidoc_headers + pylib/api_rst2md.py + +_quick_autodoc-index: + @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) SPHINX_APIDOC_OPTIONS=$(SPHINXAPIDOCENV) $(SPHINXAPIDOC) $(SPHINXAPIDOCOPTSQUICK) -o $(SOURCEDIR)/api/ $(EVDIR) $(SPHINXAPIDOCEXCLUDE) _multiversion-autodoc-index: make _autodoc-index @@ -102,6 +110,7 @@ pdf: @echo "To see result, open evennia/docs/build/latex/evennia.pdf in a PDF reader." quick: + make _quick_autodoc-index make _quick-html-build $(FILES) @echo "" @echo "Documentation built (single version, no autodocs)." @@ -121,6 +130,14 @@ local: @echo "Documentation built (single version)." @echo "To see result, open evennia/docs/build/html/index.html in a browser." +# build only that which updated since last run (no clean or index-creation) +localupdate: + make _check-env + make _html-build + @echo "" + @echo "Documentation built (single version, only updates, no auto-index)." + @echo "To see result, open evennia/docs/build/html/index.html in a browser." + # note that this should be done for each relevant multiversion branch. mv-index: make _multiversion-autodoc-index diff --git a/docs/README.md b/docs/README.md index 4912dc921e..2a9b3e6a01 100644 --- a/docs/README.md +++ b/docs/README.md @@ -348,7 +348,7 @@ See below for examples of this. This will display a one-line note that will pop even more than a normal `> note`. ```` -```important:: +```{important} This is important because it is! ``` ```` @@ -359,7 +359,7 @@ A warning block is used to draw attention to particularly dangerous things, or f mess up. ```` -```warning:: +```{warning} Be careful about this ... ```` diff --git a/docs/pylib/api_rst2md.py b/docs/pylib/api_rst2md.py new file mode 100755 index 0000000000..5bb3bc00f6 --- /dev/null +++ b/docs/pylib/api_rst2md.py @@ -0,0 +1,31 @@ +#!/usr/bin/python +""" +Remap autodoc API rst files to md files and wrap their contents. + +""" + +from glob import glob +from os.path import abspath, join as pathjoin, dirname +from os import rename + + +def _rst2md(filename_rst): + + with open(filename_rst, 'r') as fil: + # read rst file, reformat and save + txt = fil.read() + with open(filename_rst, 'w') as fil: + txt = "```{eval-rst}\n" + txt + "\n```" + fil.write(txt) + + # rename .rst file to .md file + filename, _ = filename_rst.rsplit('.', 1) + filename_md = filename + ".md" + rename(filename_rst, filename_md) + + +if __name__ == "__main__": + apidir = pathjoin(dirname(dirname(abspath(__file__))), "source", "api") + for filename_rst in glob(pathjoin(apidir, "*.rst")): + _rst2md(filename_rst) + print(" Converted {apidir}/*.rst files to .md files".format(apidir=apidir)) diff --git a/docs/pylib/auto_link_remapper.py b/docs/pylib/auto_link_remapper.py index 56b72c5631..7f3205daeb 100644 --- a/docs/pylib/auto_link_remapper.py +++ b/docs/pylib/auto_link_remapper.py @@ -9,7 +9,7 @@ import re from collections import defaultdict from sphinx.errors import DocumentError from pathlib import Path -from os.path import abspath, dirname, join as pathjoin, sep, relpath +from os.path import abspath, dirname, join as pathjoin, relpath _IGNORE_FILES = [] _SOURCEDIR_NAME = "source" @@ -19,15 +19,54 @@ _NO_REMAP_STARTSWITH = [ "http://", "https://", "github:", - "api:", "feature-request", "report-bug", "issue", "bug-report", ] - +# remove these prefixes from the url +_STRIP_PREFIX = [ + "../../api/", + "../api/", + "./api/", + "api/", + "api:", +] TXT_REMAPS = {} -URL_REMAPS = {} +# "Developer Central": "Evennia Components overview", +# "Getting Started": "Setup Quickstart", +# } +URL_REMAPS = { + "Default-Command-Help": "Default-Commands", + "./Default-Command-Help.md": "Default-Commands.md" +} +# "Developer-Central": "Components/Components-Overview", +# "Tutorials": "Howto/Howto-Overview", +# "../Howto/Starting/Directory-Overview": "Gamedir-Overview", +# "Howto/Starting/Directory-Overview": "Gamedir-Overview", +# "Starting/Directory-Overview": "Gamedir-Overview", +# "Directory-Overview": "Gamedir-Overview", +# "../Setup/Getting-Started": "Setup-Quickstart", +# "Setup/Getting-Started": "Setup-Quickstart", +# "Setup-Quickstart": "Setup-Quickstart", +# "Setup-Quickstart": "Getting-Started", # back again +# "First-Steps-Coding": "Starting-Part1", +# "../Howto/Starting/Adding-Command-Tutorial": "Adding-Commands", +# "Howto/Starting/Adding-Command-Tutorial": "Adding-Commands", +# "Starting/Adding-Command-Tutorial": "Adding-Commands", +# "Adding-Command-Tutorial": "Adding-Commands", +# "CmdSet": "Command-Sets", +# "Spawner": "Prototypes", +# "issue": "github:issue", +# "issues": "github:issue", +# "bug": "github:issue", +# "bug-report": "github:issue", +# "./Default-Command-Help": "api:evennia.commands.default#modules", +# "../Components/Default-Command-Help": "api:evennia.commands.default#modules", +# "../../../Components/Default-Command-Help": "api:evennia.commands.default#modules", +# "./Locks.md#permissions": "Permissions", +# "Permissions": "./Locks.md#permissions", # back again +# } _USED_REFS = {} @@ -96,11 +135,11 @@ def auto_link_remapper(no_autodoc=False): # normal reference-links [txt](urls) ref_regex = re.compile( - r"\[(?P[\w -\[\]\`]+?)\]\((?P.+?)\)", re.I + re.S + re.U + re.M + r"\[(?P[\n\w -\[\]\`]+?)\]\((?P.+?)\)", re.I + re.S + re.U + re.M ) # in document references ref_doc_regex = re.compile( - r"\[(?P[\w -\`]+?)\]:\s+?(?P.+?)(?=$|\n)", re.I + re.S + re.U + re.M + r"\[(?P[\n\w -\`]+?)\]:\s+?(?P.+?)(?=$|\n)", re.I + re.S + re.U + re.M ) def _sub(match): @@ -112,27 +151,38 @@ def auto_link_remapper(no_autodoc=False): txt = TXT_REMAPS.get(txt, txt) url = URL_REMAPS.get(url, url) + for strip_prefix in _STRIP_PREFIX: + if url.startswith(strip_prefix): + url = url[len(strip_prefix):] + if any(url.startswith(noremap) for noremap in _NO_REMAP_STARTSWITH): + # skip regular http/s urls etc return f"[{txt}]({url})" - if "http" in url and "://" in url: - urlout = url - else: - fname, *part = url.rsplit("/", 1) - fname = part[0] if part else fname + if url.startswith("evennia."): + # api link - we want to remove legacy #reference and remove .md + if '#' in url: + _, url = url.rsplit('#', 1) + if url.endswith(".md"): + url, _ = url.rsplit('.', 1) + return f"[{txt}]({url})" + + fname, *part = url.rsplit("/", 1) + fname = part[0] if part else fname + fname, *anchor = fname.rsplit("#", 1) + if ".md" in fname: fname = fname.rsplit(".", 1)[0] - fname, *anchor = fname.rsplit("#", 1) - if not _CURRFILE.endswith("toc.md"): - _USED_REFS[fname] = url + if not _CURRFILE.endswith("toc.md"): + _USED_REFS[fname] = url - if _CURRFILE in docref_map and fname in docref_map[_CURRFILE]: - cfilename = _CURRFILE.rsplit("/", 1)[-1] - urlout = docref_map[_CURRFILE][fname] + ("#" + anchor[0] if anchor else "") - if urlout != url: - print(f" {cfilename}: [{txt}]({url}) -> [{txt}]({urlout})") - else: - urlout = url + if _CURRFILE in docref_map and fname in docref_map[_CURRFILE]: + cfilename = _CURRFILE.rsplit("/", 1)[-1] + urlout = docref_map[_CURRFILE][fname] + ".md" + ("#" + anchor[0].lower() if anchor else "") + if urlout != url: + print(f" {cfilename}: [{txt}]({url}) -> [{txt}]({urlout})") + else: + urlout = url return f"[{txt}]({urlout})" @@ -145,11 +195,21 @@ def auto_link_remapper(no_autodoc=False): txt = TXT_REMAPS.get(txt, txt) url = URL_REMAPS.get(url, url) + for strip_prefix in _STRIP_PREFIX: + if url.startswith(strip_prefix): + url = url[len(strip_prefix):] + if any(url.startswith(noremap) for noremap in _NO_REMAP_STARTSWITH): return f"[{txt}]: {url}" + urlout = url + if "http" in url and "://" in url: urlout = url + elif url.startswith("evennia."): + # api link - we want to remove legacy #reference + if '#' in url: + _, urlout = url.rsplit('#', 1) else: fname, *part = url.rsplit("/", 1) fname = part[0] if part else fname @@ -190,12 +250,12 @@ def auto_link_remapper(no_autodoc=False): print(f" -- Auto-corrected links in {count} documents.") for (fname, src_url) in sorted(toc_map.items(), key=lambda tup: tup[0]): - if fname not in _USED_REFS: + if fname not in _USED_REFS and not src_url.startswith("api/"): print(f" ORPHANED DOC: no refs found to {src_url}.md") # write tocfile with open(_TOC_FILE, "w") as fil: - fil.write("# Toc\n") + fil.write("```{toctree}\n") if not no_autodoc: fil.write("- [API root](api/evennia-api.rst)") @@ -205,17 +265,14 @@ def auto_link_remapper(no_autodoc=False): if ref == "toc": continue - if "Part1/" in ref: - continue + # if not "/" in ref: + # ref = "./" + ref - if not "/" in ref: - ref = "./" + ref - - linkname = ref.replace("-", " ") - fil.write(f"\n- [{linkname}]({ref})") + # linkname = ref.replace("-", " ") + fil.write(f"\n{ref}") # - [{linkname}]({ref})") # we add a self-reference so the toc itself is also a part of a toctree - fil.write("\n\n```toctree::\n :hidden:\n\n toc\n```") + fil.write("\n```\n\n```{toctree}\n :hidden:\n\ntoc\n```") print(" -- Auto-Remapper finished.") diff --git a/docs/pylib/copy_from_wiki.py b/docs/pylib/copy_from_wiki.py index caf81efa96..07ab6dd8e1 100644 --- a/docs/pylib/copy_from_wiki.py +++ b/docs/pylib/copy_from_wiki.py @@ -16,7 +16,6 @@ We also need to build the toc-tree and should do so automatically for now. import glob import re import datetime -import textwrap _RE_MD_LINK = re.compile(r"\[(?P[\w -\[\]]+?)\]\((?P.+?)\)", re.I + re.S + re.U) _RE_REF_LINK = re.compile(r"\[[\w -\[\]]*?\]\(.+?\)", re.I + re.S + re.U) @@ -33,7 +32,7 @@ _INDEX_PREFIX = f""" # VERSION WARNING -> This is the experimental static v0.95 documentation of Evennia, _automatically_ generated from the +> This is the experimental static v0.9 documentation of Evennia, _automatically_ generated from the > [evennia wiki](https://github.com/evennia/evennia/wiki/) at {datetime.datetime.now()}. > There are known conversion issues which will _not_ be addressed in this version - refer to > the original wiki if you have trouble. @@ -214,7 +213,6 @@ def _sub_link(match): def create_toctree(files): - with open("../source/toc.md", "w") as fil: fil.write("# Toc\n") @@ -266,25 +264,16 @@ def convert_links(files, outdir): if text.split("\n")[0].strip().startswith("[]") else text.split("\n") ) - - # wrap text - formatted_lines = [] - for line in text: - if line.strip(): - formatted_lines.append(textwrap.fill(line, width=100)) - else: - formatted_lines.append(line) - text = "\n".join(formatted_lines) + text = "\n".join(text) if not is_index: text = f"# {title}\n\n{text}" - with open(outfile, "w") as fil: fil.write(text) if __name__ == "__main__": - - create_toctree(_INFILES) - convert_links(_INFILES, _OUTDIR) + print("This should not be run on develop files, it would overwrite changes.") + # create_toctree(_INFILES) + # convert_links(_INFILES, _OUTDIR) diff --git a/docs/pylib/fmtwidth.py b/docs/pylib/fmtwidth.py new file mode 100644 index 0000000000..4c30c5a185 --- /dev/null +++ b/docs/pylib/fmtwidth.py @@ -0,0 +1,45 @@ +#!/usr/bin python +# -*- coding: utf-8 -*- + +""" +Format given files to a max width. + +Usage: + python fmtwidth.py --width 79 ../source/**.md + +""" +import glob +import textwrap +import argparse + +_DEFAULT_WIDTH = 100 + +if __name__ == "__main__": + + parser = argparse.ArgumentParser() + + parser.add_argument("files") + parser.add_argument("-w", "--width", dest="width", type=int, default=_DEFAULT_WIDTH) + + args = parser.parse_args() + + filepaths = glob.glob(args.files, recursive=True) + width = args.width + + wrapper = textwrap.TextWrapper(width=width, break_long_words=False, expand_tabs=True,) + + count = 0 + for filepath in filepaths: + with open(filepath, "r") as fil: + lines = fil.readlines() + + outlines = [ + "\n".join(wrapper.wrap(line)) if len(line) > width else line.strip("\n") + for line in lines + ] + txt = "\n".join(outlines) + with open(filepath, "w") as fil: + fil.write(txt) + count += 1 + + print(f"Wrapped {count} files.") diff --git a/docs/pylib/update_default_cmd_index.py b/docs/pylib/update_default_cmd_index.py new file mode 100644 index 0000000000..be9316c623 --- /dev/null +++ b/docs/pylib/update_default_cmd_index.py @@ -0,0 +1,111 @@ +# +# This creates a Google wiki page for all default commands with __doc__ strings. +# +# Import this from a Django-aware shell, then call run_update. +# +# + +from os.path import dirname, abspath, join as pathjoin +from evennia.utils.utils import ( + mod_import, variable_from_module, callables_from_module +) + +__all__ = ("run_update") + + +PAGE = """ + +# Default Commands + +The full set of default Evennia commands currently contains {ncommands} commands in {nfiles} source +files. Our policy for adding default commands is outlined [here](Using-MUX-as-a-Standard). The +[Commands](Commands) documentation explains how Commands work as well as make new or customize +existing ones. Note that this page is auto-generated. Report problems to the [issue +tracker](github:issues). + +```{{note}} +Some game-states adds their own Commands which are not listed here. Examples include editing a text +with [EvEditor](EvEditor), flipping pages in [EvMore](EvMore) or using the +[Batch-Processor](Batch-Processors)'s interactive mode. +``` + +{alphabetical} + +""" + +def run_update(no_autodoc=False): + + if no_autodoc: + return + + cmdsets = ( + ("evennia.commands.default.cmdset_character", "CharacterCmdSet"), + ("evennia.commands.default.cmdset_account", "AccountCmdSet"), + ("evennia.commands.default.cmdset_unloggedin", "UnloggedinCmdSet"), + ("evennia.commands.default.cmdset_session", "SessionCmdSet"), + ) + cmd_modules = ( + "evennia.commands.default.account", + "evennia.commands.default.batchprocess", + "evennia.commands.default.building", + "evennia.commands.default.comms", + "evennia.commands.default.general", + "evennia.commands.default.help", + "evennia.commands.default.syscommandsyyp", + "evennia.commands.default.system", + "evennia.commands.default.unloggedin", + ) + + cmds_per_cmdset = {} + cmd_to_cmdset_map = {} + for modname, cmdsetname in cmdsets: + cmdset = variable_from_module(modname, variable=cmdsetname)() + cmdset.at_cmdset_creation() + cmds_per_cmdset[cmdsetname] = cmdset.commands + for cmd in cmdset.commands: + cmd_to_cmdset_map[f"{cmd.__module__}.{cmd.__class__.__name__}"] = cmdset + + cmds_per_module = {} + cmd_to_module_map = {} + cmds_alphabetically = [] + for modname in cmd_modules: + module = mod_import(modname) + cmds_per_module[module] = [ + cmd for cmd in callables_from_module(module).values() if cmd.__name__.startswith("Cmd")] + for cmd in cmds_per_module[module]: + cmd_to_module_map[cmd] = module + cmds_alphabetically.append(cmd) + cmds_alphabetically = list(sorted(cmds_alphabetically, key=lambda c: c.key)) + + cmd_infos = [] + for cmd in cmds_alphabetically: + aliases = f" [{', '.join(cmd.aliases)}]" if cmd.aliases else "" + cmdlink = f"[**{cmd.key}**{aliases}]({cmd.__module__}.{cmd.__name__})" + category = f"help-category: _{cmd.help_category.capitalize()}_" + cmdset = cmd_to_cmdset_map.get(f"{cmd.__module__}.{cmd.__name__}", None) + if cmdset: + cmodule = cmdset.__module__ + cname = cmdset.__class__.__name__ + cmdsetlink = f"cmdset: [{cname}]({cmodule}.{cname}), " + else: + # we skip commands not in the default cmdsets + continue + + cmd_infos.append(f"{cmdlink} ({cmdsetlink}{category})") + + txt = PAGE.format( + ncommands=len(cmd_to_cmdset_map), + nfiles=len(cmds_per_module), + alphabetical="\n".join(f"- {info}" for info in cmd_infos)) + + outdir = pathjoin(dirname(dirname(abspath(__file__))), "source") + fname = pathjoin(outdir, "Default-Commands.md") + + with open(fname, 'w') as fil: + fil.write(txt) + + print(" -- Updated Default Command index.") + + +if __name__ == "__main__": + run_update() diff --git a/docs/source/A-voice-operated-elevator-using-events.md b/docs/source/A-voice-operated-elevator-using-events.md index 4a38d40e20..24f6bdef33 100644 --- a/docs/source/A-voice-operated-elevator-using-events.md +++ b/docs/source/A-voice-operated-elevator-using-events.md @@ -1,7 +1,7 @@ # A voice operated elevator using events -- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events) +- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events.md) This tutorial will walk you through the steps to create a voice-operated elevator, using the [in- game Python @@ -97,7 +97,7 @@ things to decorate it a bit. But what we want now is to be able to say "1", "2" or "3" and have the elevator move in that direction. -If you have read [the previous tutorial about adding dialogues in events](./Dialogues-in-events), you +If you have read [the previous tutorial about adding dialogues in events](./Dialogues-in-events.md), you may remember what we need to do. If not, here's a summary: we need to run some code when somebody speaks in the room. So we need to create a callback (the callback will contain our lines of code). We just need to know on which event this should be set. You can enter `call here` to see the @@ -433,4 +433,4 @@ to consider adding the code in the source itself. Another possibility is to cal with the expected behavior, which makes porting code very easy. This side of chained events will be shown in the next tutorial. -- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events) +- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events.md) diff --git a/docs/source/Accounts.md b/docs/source/Accounts.md index 04b0c2d27a..6d61136583 100644 --- a/docs/source/Accounts.md +++ b/docs/source/Accounts.md @@ -1,27 +1,27 @@ # Accounts -All *users* (real people) that starts a game [Session](./Sessions) on Evennia are doing so through an +All *users* (real people) that starts a game [Session](./Sessions.md) on Evennia are doing so through an object called *Account*. The Account object has no in-game representation, it represents a unique -game account. In order to actually get on the game the Account must *puppet* an [Object](./Objects) -(normally a [Character](./Objects#Character)). +game account. In order to actually get on the game the Account must *puppet* an [Object](./Objects.md) +(normally a [Character](./Objects.md#characters)). Exactly how many Sessions can interact with an Account and its Puppets at once is determined by -Evennia's [MULTISESSION_MODE](./Sessions#Multisession-mode) setting. +Evennia's [MULTISESSION_MODE](./Sessions.md#multisession-mode) setting. Apart from storing login information and other account-specific data, the Account object is what is -chatting on [Channels](./Communications). It is also a good place to store [Permissions](./Locks) to be +chatting on [Channels](./Communications.md). It is also a good place to store [Permissions](./Locks.md) to be consistent between different in-game characters as well as configuration options. The Account -object also has its own [CmdSet](./Command-Sets), the `AccountCmdSet`. +object also has its own [CmdSet](./Command-Sets.md), the `AccountCmdSet`. Logged into default evennia, you can use the `ooc` command to leave your current -[character](./Objects) and go into OOC mode. You are quite limited in this mode, basically it works +[character](./Objects.md) and go into OOC mode. You are quite limited in this mode, basically it works like a simple chat program. It acts as a staging area for switching between Characters (if your game supports that) or as a safety mode if your Character gets deleted. Use `ic` to attempt to (re)puppet a Character. Note that the Account object can have, and often does have, a different set of -[Permissions](./Locks#Permissions) from the Character they control. Normally you should put your +[Permissions](./Locks.md#permissions) from the Character they control. Normally you should put your permissions on the Account level - this will overrule permissions set on the Character level. For the permissions of the Character to come into play the default `quell` command can be used. This allows for exploring the game using a different permission set (but you can't escalate your @@ -77,7 +77,7 @@ You should now see the Attributes on yourself. ## Properties on Accounts -Beyond those properties assigned to all typeclassed objects (see [Typeclasses](./Typeclasses)), the +Beyond those properties assigned to all typeclassed objects (see [Typeclasses](./Typeclasses.md)), the Account also has the following custom properties: - `user` - a unique link to a `User` Django object, representing the logged-in user. @@ -92,11 +92,11 @@ as - `is_superuser` (bool: True/False) - if this account is a superuser. Special handlers: -- `cmdset` - This holds all the current [Commands](./Commands) of this Account. By default these are +- `cmdset` - This holds all the current [Commands](./Commands.md) of this Account. By default these are the commands found in the cmdset defined by `settings.CMDSET_ACCOUNT`. -- `nicks` - This stores and handles [Nicks](./Nicks), in the same way as nicks it works on Objects. +- `nicks` - This stores and handles [Nicks](./Nicks.md), in the same way as nicks it works on Objects. For Accounts, nicks are primarily used to store custom aliases for -[Channels](./Communications#Channels). +[Channels](./Communications.md#channels). Selection of special methods (see `evennia.DefaultAccount` for details): - `get_puppet` - get a currently puppeted object connected to the Account and a given session id, if diff --git a/docs/source/Add-a-wiki-on-your-website.md b/docs/source/Add-a-wiki-on-your-website.md index ab81e08bef..a8f476d28e 100644 --- a/docs/source/Add-a-wiki-on-your-website.md +++ b/docs/source/Add-a-wiki-on-your-website.md @@ -2,7 +2,7 @@ **Before doing this tutorial you will probably want to read the intro in -[Basic Web tutorial](./Web-Tutorial).** Reading the three first parts of the +[Basic Web tutorial](./Web-Tutorial.md).** Reading the three first parts of the [Django tutorial](https://docs.djangoproject.com/en/1.9/intro/tutorial01/) might help as well. This tutorial will provide a step-by-step process to installing a wiki on your website. diff --git a/docs/source/Adding-Command-Tutorial.md b/docs/source/Adding-Command-Tutorial.md index 36e1600542..569c12252d 100644 --- a/docs/source/Adding-Command-Tutorial.md +++ b/docs/source/Adding-Command-Tutorial.md @@ -1,6 +1,6 @@ # Adding Command Tutorial -This is a quick first-time tutorial expanding on the [Commands](./Commands) documentation. +This is a quick first-time tutorial expanding on the [Commands](./Commands.md) documentation. Let's assume you have just downloaded Evennia, installed it and created your game folder (let's call it just `mygame` here). Now you want to try to add a new command. This is the fastest way to do it. @@ -16,7 +16,7 @@ example code. 1. Give your class a useful _docstring_. A docstring is the string at the very top of a class or function/method. The docstring at the top of the command class is read by Evennia to become the help entry for the Command (see - [Command Auto-help](./Help-System#command-auto-help-system)). + [Command Auto-help](./Help-System.md#command-auto-help-system)). 1. Define a class method `func(self)` that echoes your input back to you. Below is an example how this all could look for the echo command: @@ -47,7 +47,7 @@ Below is an example how this all could look for the echo command: ## Step 2: Adding the Command to a default Cmdset -The command is not available to use until it is part of a [Command Set](./Command-Sets). In this +The command is not available to use until it is part of a [Command Set](./Command-Sets.md). In this example we will go the easiest route and add it to the default Character commandset that already exists. @@ -87,13 +87,13 @@ your command definition). by its argument `test` (which will end up in `self.args). To change this behavior, you can add the `arg_regex` property alongside `key`, `help_category` etc. [See the arg_regex -documentation](Commands#on-arg_regex) for more info. +documentation](./Commands.md#on-arg_regex) for more info. If you want to overload existing default commands (such as `look` or `get`), just add your new command with the same key as the old one - it will then replace it. Just remember that you must use `@reload` to see any changes. -See [Commands](./Commands) for many more details and possibilities when defining Commands and using +See [Commands](./Commands.md) for many more details and possibilities when defining Commands and using Cmdsets in various ways. @@ -102,7 +102,7 @@ Cmdsets in various ways. Adding your Command to the `CharacterCmdSet` is just one easy exapmple. The cmdset system is very generic. You can create your own cmdsets (let's say in a module `mycmdsets.py`) and add them to objects as you please (how to control their merging is described in detail in the [Command Set -documentation](Command-Sets)). +documentation](./Command-Sets.md)). ```python # file mygame/commands/mycmdsets.py @@ -131,7 +131,7 @@ only make the new merged cmdset permanent on that *single* object. Often you wan this particular class to have this cmdset. To make sure all new created objects get your new merged set, put the `cmdset.add` call in your -custom [Typeclasses](./Typeclasses)' `at_object_creation` method: +custom [Typeclasses](./Typeclasses.md)' `at_object_creation` method: ```python # e.g. in mygame/typeclasses/objects.py diff --git a/docs/source/Adding-Object-Typeclass-Tutorial.md b/docs/source/Adding-Object-Typeclass-Tutorial.md index 4e532a5c75..4e4e0b66bb 100644 --- a/docs/source/Adding-Object-Typeclass-Tutorial.md +++ b/docs/source/Adding-Object-Typeclass-Tutorial.md @@ -13,9 +13,9 @@ When you create a new Evennia game (with for example `evennia --init mygame`) Ev automatically create empty child classes `Object`, `Character`, `Room` and `Exit` respectively. They are found `mygame/typeclasses/objects.py`, `mygame/typeclasses/rooms.py` etc. -> Technically these are all [Typeclassed](./Typeclasses), which can be ignored for now. In +> Technically these are all [Typeclassed](./Typeclasses.md), which can be ignored for now. In > `mygame/typeclasses` are also base typeclasses for out-of-character things, notably -> [Channels](./Communications), [Accounts](./Accounts) and [Scripts](./Scripts). We don't cover those in +> [Channels](./Communications.md), [Accounts](./Accounts.md) and [Scripts](./Scripts.md). We don't cover those in > this tutorial. For your own game you will most likely want to expand on these very simple beginnings. It's normal @@ -62,13 +62,13 @@ up. you will find the traceback. The most common error is that you have some sort of syntax error in your class. -Note that the [Locks](./Locks) and [Attribute](./Attributes) which are set in the typeclass could just +Note that the [Locks](./Locks.md) and [Attribute](./Attributes.md) which are set in the typeclass could just as well have been set using commands in-game, so this is a *very* simple example. ## Storing data on initialization The `at_object_creation` is only called once, when the object is first created. This makes it ideal -for database-bound things like [Attributes](./Attributes). But sometimes you want to create temporary +for database-bound things like [Attributes](./Attributes.md). But sometimes you want to create temporary properties (things that are not to be stored in the database but still always exist every time the object is created). Such properties can be initialized in the `at_init` method on the object. `at_init` is called every time the object is loaded into memory. @@ -86,7 +86,7 @@ def at_init(self): self.ndb.mylist = [] ``` -> Note: As mentioned in the [Typeclasses](./Typeclasses) documentation, `at_init` replaces the use of +> Note: As mentioned in the [Typeclasses](./Typeclasses.md) documentation, `at_init` replaces the use of > the standard `__init__` method of typeclasses due to how the latter may be called in situations > other than you'd expect. So use `at_init` where you would normally use `__init__`. diff --git a/docs/source/Administrative-Docs.md b/docs/source/Administrative-Docs.md index c37c64a7cd..154fbd83ec 100644 --- a/docs/source/Administrative-Docs.md +++ b/docs/source/Administrative-Docs.md @@ -5,48 +5,48 @@ are responsible for managing the game. ### Installation and Early Life -- [Choosing (and installing) an SQL Server](./Choosing-An-SQL-Server) -- [Getting Started - Installing Evennia](./Getting-Started) -- [Running Evennia in Docker Containers](./Running-Evennia-in-Docker) -- [Starting, stopping, reloading and resetting Evennia](./Start-Stop-Reload) -- [Keeping your game up to date](./Updating-Your-Game) - - [Resetting your database](./Updating-Your-Game#resetting-your-database) -- [Making your game available online](./Online-Setup) - - [Hosting options](./Online-Setup#hosting-options) - - [Securing your server with SSL/Let's Encrypt](./Online-Setup#ssl) -- [Listing your game](./Evennia-Game-Index) at the online [Evennia game +- [Choosing (and installing) an SQL Server](./Choosing-An-SQL-Server.md) +- [Getting Started - Installing Evennia](./Getting-Started.md) +- [Running Evennia in Docker Containers](./Running-Evennia-in-Docker.md) +- [Starting, stopping, reloading and resetting Evennia](./Start-Stop-Reload.md) +- [Keeping your game up to date](./Updating-Your-Game.md) + - [Resetting your database](./Updating-Your-Game.md#resetting-your-database) +- [Making your game available online](./Online-Setup.md) + - [Hosting options](./Online-Setup.md#hosting-options) + - [Securing your server with SSL/Let's Encrypt](./Online-Setup.md#ssl) +- [Listing your game](./Evennia-Game-Index.md) at the online [Evennia game index](http://games.evennia.com) ### Customizing the server -- [Changing the Settings](./Server-Conf#Settings-file) +- [Changing the Settings](./Server-Conf.md#settings-file) - [Available Master Settings](https://github.com/evennia/evennia/blob/master/evennia/settings_default.py) -- [Change Evennia's language](./Internationalization) (internationalization) -- [Apache webserver configuration](./Apache-Config) (optional) -- [Changing text encodings used by the server](./Text-Encodings) -- [The Connection Screen](./Connection-Screen) -- [Guest Logins](./Guest-Logins) -- [How to connect Evennia to IRC channels](./IRC) -- [How to connect Evennia to RSS feeds](./RSS) -- [How to connect Evennia to Grapevine](./Grapevine) -- [How to connect Evennia to Twitter](./How-to-connect-Evennia-to-Twitter) +- [Change Evennia's language](./Internationalization.md) (internationalization) +- [Apache webserver configuration](./Apache-Config.md) (optional) +- [Changing text encodings used by the server](./Text-Encodings.md) +- [The Connection Screen](./Connection-Screen.md) +- [Guest Logins](./Guest-Logins.md) +- [How to connect Evennia to IRC channels](./IRC.md) +- [How to connect Evennia to RSS feeds](./RSS.md) +- [How to connect Evennia to Grapevine](./Grapevine.md) +- [How to connect Evennia to Twitter](./How-to-connect-Evennia-to-Twitter.md) ### Administrating the running game -- [Supported clients](./Client-Support-Grid) (grid of known client issues) -- [Changing Permissions](./Building-Permissions) of users -- [Banning](./Banning) and deleting users - - [Summary of abuse-handling tools](./Banning#summary-of-abuse-handling-tools) in the default cmdset +- [Supported clients](./Client-Support-Grid.md) (grid of known client issues) +- [Changing Permissions](./Building-Permissions.md) of users +- [Banning](./Banning.md) and deleting users + - [Summary of abuse-handling tools](./Banning.md#summary-of-abuse-handling-tools) in the default cmdset ### Working with Evennia -- [Setting up your work environment with version control](./Version-Control) -- [First steps coding with Evennia](./First-Steps-Coding) -- [Setting up a continuous integration build environment](./Continuous-Integration) +- [Setting up your work environment with version control](./Version-Control.md) +- [First steps coding with Evennia](./First-Steps-Coding.md) +- [Setting up a continuous integration build environment](./Continuous-Integration.md) -```toctree:: +```{toctree} :hidden: Choosing-An-SQL-Server diff --git a/docs/source/Arxcode-installing-help.md b/docs/source/Arxcode-installing-help.md index 3876b841f9..e7efdfae28 100644 --- a/docs/source/Arxcode-installing-help.md +++ b/docs/source/Arxcode-installing-help.md @@ -11,7 +11,7 @@ to pick ideas or even get a starting game to build on. These instructions are ba released as of *Aug 12, 2018*. If you are not familiar with what Evennia is, you can read -[an introduction here](./Evennia-Introduction). +[an introduction here](./Evennia-Introduction.md). It's not too hard to run Arx from the sources (of course you'll start with an empty database) but since part of Arx has grown organically, it doesn't follow standard Evennia paradigms everywhere. @@ -24,7 +24,7 @@ Firstly, set aside a folder/directory on your drive for everything to follow. You need to start by installing [Evennia](http://www.evennia.com) by following most of the [Getting Started -Instructions](Getting-Started) for your OS. The difference is that you need to `git clone +Instructions](./Getting-Started.md) for your OS. The difference is that you need to `git clone https://github.com/TehomCD/evennia.git` instead of Evennia's repo because Arx uses TehomCD's older Evennia 0.8 [fork](https://github.com/TehomCD/evennia), notably still using Python2. This detail is important if referring to newer Evennia documentation. @@ -32,7 +32,7 @@ important if referring to newer Evennia documentation. If you are new to Evennia it's *highly* recommended that you run through the instructions in full - including initializing and starting a new empty game and connecting to it. That way you can be sure Evennia works correctly as a base line. If you have trouble, make sure to -read the [Troubleshooting instructions](./Getting-Started#troubleshooting) for your +read the [Troubleshooting instructions](./Getting-Started.md#troubleshooting) for your operating system. You can also drop into our [forums](https://groups.google.com/forum/#%21forum/evennia), join `#evennia` on `irc.freenode.net` or chat from the linked [Discord Server](https://discord.gg/NecFePw). @@ -64,7 +64,7 @@ A new folder `myarx` should appear next to the ones you already had. You could r something else if you want. Cd into `myarx`. If you wonder about the structure of the game dir, you can [read more about it -here](Directory-Overview). +here](./Directory-Overview.md). ### Clean up settings diff --git a/docs/source/Async-Process.md b/docs/source/Async-Process.md index ae18635738..e44e9330a2 100644 --- a/docs/source/Async-Process.md +++ b/docs/source/Async-Process.md @@ -90,7 +90,7 @@ line quite pointless for processing any data from the function. Instead one has - `at_err_kwargs` - an optional dictionary that will be fed as keyword arguments to the `at_err` errback. -An example of making an asynchronous call from inside a [Command](./Commands) definition: +An example of making an asynchronous call from inside a [Command](./Commands.md) definition: ```python from evennia import utils, Command @@ -139,7 +139,7 @@ sleep. ``` This will delay the execution of the callback for 10 seconds. This function is explored much more in -the [Command Duration Tutorial](./Command-Duration). +the [Command Duration Tutorial](./Command-Duration.md). You can also try the following snippet just see how it works: diff --git a/docs/source/Attributes.md b/docs/source/Attributes.md index 4ca0e82566..b04d18f654 100644 --- a/docs/source/Attributes.md +++ b/docs/source/Attributes.md @@ -7,8 +7,8 @@ can give correct subsequent commands. If you are writing a combat system, you mi combattant's next roll get easier dependent on if their opponent failed. Your characters will probably need to store roleplaying-attributes like strength and agility. And so on. -[Typeclassed](./Typeclasses) game entities ([Accounts](./Accounts), [Objects](./Objects), -[Scripts](./Scripts) and [Channels](./Communications)) always have *Attributes* associated with them. +[Typeclassed](./Typeclasses.md) game entities ([Accounts](./Accounts.md), [Objects](./Objects.md), +[Scripts](./Scripts.md) and [Channels](./Communications.md)) always have *Attributes* associated with them. Attributes are used to store any type of data 'on' such entities. This is different from storing data in properties already defined on entities (such as `key` or `location`) - these have very specific names and require very specific types of data (for example you couldn't assign a python @@ -16,12 +16,12 @@ specific names and require very specific types of data (for example you couldn't want to assign arbitrary data to arbitrary names. **Attributes are _not_ secure by default and any player may be able to change them unless you -[prevent this behavior](./Attributes#locking-and-checking-attributes).** +[prevent this behavior](./Attributes.md#locking-and-checking-attributes).** ## The .db and .ndb shortcuts To save persistent data on a Typeclassed object you normally use the `db` (DataBase) operator. Let's -try to save some data to a *Rose* (an [Object](./Objects)): +try to save some data to a *Rose* (an [Object](./Objects.md)): ```python # saving @@ -87,13 +87,13 @@ The handlers have normal access methods that allow you to manage and retrieve `A returned, but the method takes keywords for returning the Attribute object itself. By supplying an `accessing_object` to the call one can also make sure to check permissions before modifying anything. -- `add(...)` - this adds a new Attribute to the object. An optional [lockstring](./Locks) can be +- `add(...)` - this adds a new Attribute to the object. An optional [lockstring](./Locks.md) can be supplied here to restrict future access and also the call itself may be checked against locks. - `remove(...)` - Remove the given Attribute. This can optionally be made to check for permission before performing the deletion. - `clear(...)` - removes all Attributes from object. - `all(...)` - returns all Attributes (of the given category) attached to this object. -See [this section](./Attributes#locking-and-checking-attributes) for more about locking down Attribute +See [this section](./Attributes.md#locking-and-checking-attributes) for more about locking down Attribute access and editing. The `Nattribute` offers no concept of access control. Some examples: @@ -118,23 +118,23 @@ An Attribute object is stored in the database. It has the following properties: to `attrname`. - `value` - this is the value of the Attribute. This value can be anything which can be pickled - objects, lists, numbers or what have you (see - [this section](./Attributes#What_types_of_data_can_I_save_in_an_Attribute) for more info). In the + [this section](./Attributes.md#what-types-of-data-can-i-save-in-an-attribute) for more info). In the example `obj.db.attrname = value`, the `value` is stored here. - `category` - this is an optional property that is set to None for most Attributes. Setting this allows to use Attributes for different functionality. This is usually not needed unless you want - to use Attributes for very different functionality ([Nicks](./Nicks) is an example of using + to use Attributes for very different functionality ([Nicks](./Nicks.md) is an example of using Attributes in this way). To modify this property you need to use the [Attribute -Handler](Attributes#The_Attribute_Handler). +Handler](#the-attributehandler). - `strvalue` - this is a separate value field that only accepts strings. This severely limits the data possible to store, but allows for easier database lookups. This property is usually not used - except when re-using Attributes for some other purpose ([Nicks](./Nicks) use it). It is only - accessible via the [Attribute Handler](./Attributes#The_Attribute_Handler). + except when re-using Attributes for some other purpose ([Nicks](./Nicks.md) use it). It is only + accessible via the [Attribute Handler](./Attributes.md#the-attributehandler). There are also two special properties: -- `attrtype` - this is used internally by Evennia to separate [Nicks](./Nicks), from Attributes (Nicks +- `attrtype` - this is used internally by Evennia to separate [Nicks](./Nicks.md), from Attributes (Nicks use Attributes behind the scenes). - `model` - this is a *natural-key* describing the model this Attribute is attached to. This is on the form *appname.modelclass*, like `objects.objectdb`. It is used by the Attribute and @@ -162,7 +162,7 @@ default during heavy loads. - A more valid reason for using non-persistent data is if you *want* to lose your state when logging off. Maybe you are storing throw-away data that are re-initialized at server startup. Maybe you - are implementing some caching of your own. Or maybe you are testing a buggy [Script](./Scripts) that + are implementing some caching of your own. Or maybe you are testing a buggy [Script](./Scripts.md) that does potentially harmful stuff to your character object. With non-persistent storage you can be sure that whatever is messed up, it's nothing a server reboot can't clear up. @@ -192,7 +192,7 @@ not a big deal. But if you are accessing the Attribute as part of some big loop amount of reads/writes you should first extract it to a temporary variable, operate on *that* and then save the result back to the Attribute. If you are storing a more complex structure like a `dict` or a `list` you should make sure to "disconnect" it from the database before looping over it, -as mentioned in the [Retrieving Mutable Objects](./Attributes#retrieving-mutable-objects) section +as mentioned in the [Retrieving Mutable Objects](./Attributes.md#retrieving-mutable-objects) section below. ### Storing single objects @@ -246,7 +246,7 @@ containing dicts, etc. Since you can use any combination of the above iterables, this is generally not much of a limitation. -Any entity listed in the [Single object](./Attributes#Storing-Single-Objects) section above can be +Any entity listed in the [Single object](./Attributes.md#storing-single-objects) section above can be stored in the iterable. > As mentioned in the previous section, database entities (aka typeclasses) are not possible to @@ -353,7 +353,7 @@ already disconnected from the database from the onset. Attributes are normally not locked down by default, but you can easily change that for individual Attributes (like those that may be game-sensitive in games with user-level building). -First you need to set a *lock string* on your Attribute. Lock strings are specified [Locks](./Locks). +First you need to set a *lock string* on your Attribute. Lock strings are specified [Locks](./Locks.md). The relevant lock types are - `attrread` - limits who may read the value of the Attribute diff --git a/docs/source/Banning.md b/docs/source/Banning.md index afb17874d8..09baae2b95 100644 --- a/docs/source/Banning.md +++ b/docs/source/Banning.md @@ -114,14 +114,14 @@ is not what you want in this case. - **cboot mychannel = thomas** -- Boot a subscriber from a channel you control - **clock mychannel = control:perm(Admin);listen:all();send:all()** -- Fine control of access to -your channel using [lock definitions](./Locks). +your channel using [lock definitions](./Locks.md). Locking a specific command (like `page`) is accomplished like so: 1. Examine the source of the command. [The default `page` command class]( https://github.com/evennia/evennia/blob/master/evennia/commands/default/comms.py#L686) has the lock string **"cmd:not pperm(page_banned)"**. This means that unless the player has the 'permission' "page_banned" they can use this command. You can assign any lock string to allow finer customization -in your commands. You might look for the value of an [Attribute](./Attributes) or [Tag](./Tags), your +in your commands. You might look for the value of an [Attribute](./Attributes.md) or [Tag](./Tags.md), your current location etc. 2. **perm/account thomas = page_banned** -- Give the account the 'permission' which causes (in this case) the lock to fail. diff --git a/docs/source/Batch-Code-Processor.md b/docs/source/Batch-Code-Processor.md index eeb82b8879..df8eaff1ff 100644 --- a/docs/source/Batch-Code-Processor.md +++ b/docs/source/Batch-Code-Processor.md @@ -1,7 +1,7 @@ # Batch Code Processor -For an introduction and motivation to using batch processors, see [here](./Batch-Processors). This +For an introduction and motivation to using batch processors, see [here](./Batch-Processors.md). This page describes the Batch-*code* processor. The Batch-*command* one is covered [here](Batch-Command- Processor). @@ -192,7 +192,7 @@ connect that room with a room you built in the current block. There are two ways - Perform a database search for the name of the room you created (since you cannot know in advance which dbref it got assigned). The problem is that a name may not be unique (you may have a lot of "A -dark forest" rooms). There is an easy way to handle this though - use [Tags](./Tags) or *Aliases*. You +dark forest" rooms). There is an easy way to handle this though - use [Tags](./Tags.md) or *Aliases*. You can assign any number of tags and/or aliases to any object. Make sure that one of those tags or aliases is unique to the room (like "room56") and you will henceforth be able to always uniquely search and find it later. diff --git a/docs/source/Batch-Command-Processor.md b/docs/source/Batch-Command-Processor.md index 9999e7e8f5..9278b4be7f 100644 --- a/docs/source/Batch-Command-Processor.md +++ b/docs/source/Batch-Command-Processor.md @@ -1,7 +1,7 @@ # Batch Command Processor -For an introduction and motivation to using batch processors, see [here](./Batch-Processors). This +For an introduction and motivation to using batch processors, see [here](./Batch-Processors.md). This page describes the Batch-*command* processor. The Batch-*code* one is covered [here](Batch-Code- Processor). @@ -152,7 +152,7 @@ when creating the file, so that you can 'walk' (or teleport) to the right places This also means there are several pitfalls when designing and adding certain types of objects. Here are some examples: -- *Rooms that change your [Command Set](./Command-Sets)*: Imagine that you build a 'dark' room, which +- *Rooms that change your [Command Set](./Command-Sets.md)*: Imagine that you build a 'dark' room, which severely limits the cmdsets of those entering it (maybe you have to find the light switch to proceed). In your batch script you would create this room, then teleport to it - and promptly be shifted into the dark state where none of your normal build commands work ... @@ -172,7 +172,7 @@ The fact that you build as 'yourself' can also be considered an advantage howeve decide to change the default command to allow others than superusers to call the processor. Since normal access-checks are still performed, a malevolent builder with access to the processor should not be able to do all that much damage (this is the main drawback of the [Batch Code -Processor](Batch-Code-Processor)) +Processor](./Batch-Code-Processor.md)) - [GNU Emacs](https://www.gnu.org/software/emacs/) users might find it interesting to use emacs' *evennia mode*. This is an Emacs major mode found in `evennia/utils/evennia-mode.el`. It offers diff --git a/docs/source/Batch-Processors.md b/docs/source/Batch-Processors.md index ff634d7ce7..85a4c8a30f 100644 --- a/docs/source/Batch-Processors.md +++ b/docs/source/Batch-Processors.md @@ -35,8 +35,8 @@ just list in-game commands in a text file. The code-processor on the other hand powerful but also more complex - it lets you use Evennia's API to code your world in full-fledged Python code. -- The [Batch Command Processor](./Batch-Command-Processor) -- The [Batch Code Processor](./Batch-Code-Processor) +- The [Batch Command Processor](./Batch-Command-Processor.md) +- The [Batch Code Processor](./Batch-Code-Processor.md) If you plan to use international characters in your batchfiles you are wise to read about *file encodings* below. @@ -73,7 +73,7 @@ need to add the editor's encoding to Evennia's `ENCODINGS` list. If you are unsu file with lots of non-ASCII letters in the editor of your choice, then import to make sure it works as it should. -More help with encodings can be found in the entry [Text Encodings](./Text-Encodings) and also in the +More help with encodings can be found in the entry [Text Encodings](./Text-Encodings.md) and also in the Wikipedia article [here](http://en.wikipedia.org/wiki/Text_encodings). **A footnote for the batch-code processor**: Just because *Evennia* can parse your file and your diff --git a/docs/source/Bootstrap-Components-and-Utilities.md b/docs/source/Bootstrap-Components-and-Utilities.md index f8590fcc7e..5e46964766 100644 --- a/docs/source/Bootstrap-Components-and-Utilities.md +++ b/docs/source/Bootstrap-Components-and-Utilities.md @@ -2,8 +2,8 @@ Bootstrap provides many utilities and components you can use when customizing Evennia's web presence. We'll go over a few examples here that you might find useful. -> Please take a look at either [the basic web tutorial](./Add-a-simple-new-web-page) or [the web -character view tutorial](Web-Character-View-Tutorial) +> Please take a look at either [the basic web tutorial](./Add-a-simple-new-web-page.md) or [the web +character view tutorial](./Web-Character-View-Tutorial.md) > to get a feel for how to add pages to Evennia's website to test these examples. ## General Styling @@ -79,4 +79,4 @@ width of the page - Evennia's base site uses the former. ### Forms [Forms](https://getbootstrap.com/docs/4.0/components/forms/) are highly customizable with Bootstrap. For a more in-depth look at how to use forms and their styles in your own Evennia site, please read -over [the web character gen tutorial.](./Web-Character-Generation) \ No newline at end of file +over [the web character gen tutorial.](./Web-Character-Generation.md) \ No newline at end of file diff --git a/docs/source/Builder-Docs.md b/docs/source/Builder-Docs.md index 48331464ab..9bd7a11a05 100644 --- a/docs/source/Builder-Docs.md +++ b/docs/source/Builder-Docs.md @@ -4,29 +4,29 @@ This section contains information useful to world builders. ### Building basics -- [Default in-game commands](api:evennia.commands.default) -- [Building Quick-start](./Building-Quickstart) -- [Giving build permissions to others](./Building-Permissions) -- [Adding text tags](./TextTags) - - [Colored text](./TextTags#coloured-text) - - [Clickable links](./TextTags#clickable-links) - - [Inline functions](./TextTags#inline-functions) -- [Customizing the connection screen](./Connection-Screen) +- [Default in-game commands](evennia.commands.default) +- [Building Quick-start](./Building-Quickstart.md) +- [Giving build permissions to others](./Building-Permissions.md) +- [Adding text tags](./TextTags.md) + - [Colored text](./TextTags.md#coloured-text) + - [Clickable links](./TextTags.md#clickable-links) + - [Inline functions](./TextTags.md#inline-functions) +- [Customizing the connection screen](./Connection-Screen.md) ### Advanced building and World building -- [Overview of batch processors](./Batch-Processors) - - [Batch-command processor](./Batch-Command-Processor) - - [Batch-code processor](./Batch-Code-Processor) -- [Using the Spawner for individualizing objects](./Spawner-and-Prototypes) -- [Adding Zones](./Zones) +- [Overview of batch processors](./Batch-Processors.md) + - [Batch-command processor](./Batch-Command-Processor.md) + - [Batch-code processor](./Batch-Code-Processor.md) +- [Using the Spawner for individualizing objects](./Spawner-and-Prototypes.md) +- [Adding Zones](./Zones.md) ### The Tutorial world -- [Introduction and setup](./Tutorial-World-Introduction) +- [Introduction and setup](./Tutorial-World-Introduction.md) -```toctree:: +```{toctree} :hidden: Building-Quickstart diff --git a/docs/source/Building-Permissions.md b/docs/source/Building-Permissions.md index 38e7e80c8d..2f41d9c95b 100644 --- a/docs/source/Building-Permissions.md +++ b/docs/source/Building-Permissions.md @@ -2,7 +2,7 @@ *OBS: This gives only a brief introduction to the access system. Locks and permissions are fully -detailed* [here](./Locks). +detailed* [here](./Locks.md). ## The super user @@ -17,7 +17,7 @@ but one superuser. Whereas permissions can be used for anything, those put in `settings.PERMISSION_HIERARCHY` will have a ranking relative each other as well. We refer to these types of permissions as *hierarchical -permissions*. When building locks to check these permissions, the `perm()` [lock function](./Locks) is +permissions*. When building locks to check these permissions, the `perm()` [lock function](./Locks.md) is used. By default Evennia creates the following hierarchy (spelled exactly like this): 1. **Developers** basically have the same access as superusers except that they do *not* sidestep diff --git a/docs/source/Building-Quickstart.md b/docs/source/Building-Quickstart.md index be4ad9d290..64fa277a0f 100644 --- a/docs/source/Building-Quickstart.md +++ b/docs/source/Building-Quickstart.md @@ -1,8 +1,8 @@ # Building Quickstart -The [default command](./Default-Command-Help) definitions coming with Evennia -follows a style [similar](./Using-MUX-as-a-Standard) to that of MUX, so the +The [default command](./Default-Commands.md) definitions coming with Evennia +follows a style [similar](./Using-MUX-as-a-Standard.md) to that of MUX, so the commands should be familiar if you used any such code bases before. > Throughout the larger documentation you may come across commands prefixed @@ -85,14 +85,14 @@ dropped in the room, then try this: lock box = get:false() -Locks represent a rather [big topic](./Locks), but for now that will do what we want. This will lock +Locks represent a rather [big topic](./Locks.md), but for now that will do what we want. This will lock the box so noone can lift it. The exception is superusers, they override all locks and will pick it up anyway. Make sure you are quelling your superuser powers and try to get the box now: > get box You can't get that. -Think thís default error message looks dull? The `get` command looks for an [Attribute](./Attributes) +Think thís default error message looks dull? The `get` command looks for an [Attribute](./Attributes.md) named `get_err_msg` for returning a nicer error message (we just happen to know this, you would need to peek into the [code](https://github.com/evennia/evennia/blob/master/evennia/commands/default/general.py#L235) for @@ -110,11 +110,11 @@ the raw description of your current room (including color codes), so that you ca set its description to something else. You create new Commands (or modify existing ones) in Python outside the game. See the [Adding -Commands tutorial](Adding-Command-Tutorial) for help with creating your first own Command. +Commands tutorial](./Adding-Command-Tutorial.md) for help with creating your first own Command. ## Get a Personality -[Scripts](./Scripts) are powerful out-of-character objects useful for many "under the hood" things. +[Scripts](./Scripts.md) are powerful out-of-character objects useful for many "under the hood" things. One of their optional abilities is to do things on a timer. To try out a first script, let's put one on ourselves. There is an example script in `evennia/contrib/tutorial_examples/bodyfunctions.py` that is called `BodyFunctions`. To add this to us we will use the `script` command: @@ -137,14 +137,14 @@ When you are tired of your character's "insights", kill the script with script/stop self = tutorial_examples.bodyfunctions.BodyFunctions You create your own scripts in Python, outside the game; the path you give to `script` is literally -the Python path to your script file. The [Scripts](./Scripts) page explains more details. +the Python path to your script file. The [Scripts](./Scripts.md) page explains more details. ## Pushing Your Buttons If we get back to the box we made, there is only so much fun you can do with it at this point. It's just a dumb generic object. If you renamed it to `stone` and changed its description noone would be -the wiser. However, with the combined use of custom [Typeclasses](./Typeclasses), [Scripts](./Scripts) -and object-based [Commands](./Commands), you could expand it and other items to be as unique, complex +the wiser. However, with the combined use of custom [Typeclasses](./Typeclasses.md), [Scripts](./Scripts.md) +and object-based [Commands](./Commands.md), you could expand it and other items to be as unique, complex and interactive as you want. Let's take an example. So far we have only created objects that use the default object typeclass @@ -161,7 +161,7 @@ sure to look in`evennia/contrib/` so you don't have to write the full path every - one red button. The RedButton is an example object intended to show off a few of Evennia's features. You will find -that the [Typeclass](./Typeclasses) and [Commands](./Commands) controlling it are inside +that the [Typeclass](./Typeclasses.md) and [Commands](./Commands.md) controlling it are inside `evennia/contrib/tutorial_examples/`. If you wait for a while (make sure you dropped it!) the button will blink invitingly. Why don't you diff --git a/docs/source/Building-a-mech-tutorial.md b/docs/source/Building-a-mech-tutorial.md index 48601ebcdf..9d14bcbfc3 100644 --- a/docs/source/Building-a-mech-tutorial.md +++ b/docs/source/Building-a-mech-tutorial.md @@ -28,9 +28,9 @@ Before we continue, let’s make a brief detour. Evennia is very flexible about more flexible about using and adding commands to those objects. Here are some ground rules well worth remembering for the remainder of this article: -- The [Account](./Accounts) represents the real person logging in and has no game-world existence. -- Any [Object](./Objects) can be puppeted by an Account (with proper permissions). -- [Characters](./Objects#characters), [Rooms](./Objects#rooms), and [Exits](./Objects#exits) are just +- The [Account](./Accounts.md) represents the real person logging in and has no game-world existence. +- Any [Object](./Objects.md) can be puppeted by an Account (with proper permissions). +- [Characters](./Objects.md#characters), [Rooms](./Objects.md#rooms), and [Exits](./Objects.md#exits) are just children of normal Objects. - Any Object can be inside another (except if it creates a loop). - Any Object can store custom sets of commands on it. Those commands can: @@ -120,7 +120,7 @@ about the missiles being fired and has different `key` and `aliases`. We leave that up to you to create as an exercise. You could have it print "WOOSH! The mech launches missiles against !", for example. -Now we shove our commands into a command set. A [Command Set](./Command-Sets) (CmdSet) is a container +Now we shove our commands into a command set. A [Command Set](./Command-Sets.md) (CmdSet) is a container holding any number of commands. The command set is what we will store on the mech. ```python @@ -173,7 +173,7 @@ This is great for testing. The way we added it, the MechCmdSet will even go away server. Now we want to make the mech an actual object “type” so we can create mechs without those extra steps. For this we need to create a new Typeclass. -A [Typeclass](./Typeclasses) is a near-normal Python class that stores its existence to the database +A [Typeclass](./Typeclasses.md) is a near-normal Python class that stores its existence to the database behind the scenes. A Typeclass is created in a normal Python source file: ```python diff --git a/docs/source/Client-Support-Grid.md b/docs/source/Client-Support-Grid.md index 1a9fc0ef61..1acd9e257c 100644 --- a/docs/source/Client-Support-Grid.md +++ b/docs/source/Client-Support-Grid.md @@ -1,96 +1,73 @@ # Client Support Grid This grid tries to gather info about different MU clients when used with Evennia. -If you want to report a problem, update an entry or add a client, make a +If you want to report a problem, update an entry or add a client, make a new [documentation issue](github:issue) for it. Everyone's encouraged to report their findings. -##### Legend: +## Client Grid + +Legend: - **Name**: The name of the client. Also note if it's OS-specific. - **Version**: Which version or range of client versions were tested. - **Comments**: Any quirks on using this client with Evennia should be added here. -## Client Grid -```eval_rst +| Name | Version tested | Comments | +| --- | --- | --- | +| [Evennia Webclient][1] | 1.0+ | Evennia-specific | +| [tintin++][2] | 2.0+ | No MXP support | +| [tinyfugue][3] | 5.0+ | No UTF-8 support | +| [MUSHclient][4] (Win) | 4.94 | NAWS reports full text area | +| [Zmud][5] (Win) | 7.21 | *UNTESTED* | +| [Cmud][6] (Win) | v3 | *UNTESTED* | +| [Potato][7]_ | 2.0.0b16 | No MXP, MCCP support. Win 32bit does not understand | +| | | "localhost", must use `127.0.0.1`. | +| [Mudlet][8] | 3.4+ | No known issues. Some older versions showed <> as html | +| | | under MXP. | +| [SimpleMU][9] (Win) | full | Discontinued. NAWS reports pixel size. | +| [Atlantis][10] (Mac) | 0.9.9.4 | No known issues. | +| [GMUD][11] | 0.0.1 | Can't handle any telnet handshakes. Not recommended. | +| [BeipMU][12] (Win) | 3.0.255 | No MXP support. Best to enable "MUD prompt handling", disable | +| | | "Handle HTML tags". | +| [MudRammer][13] (IOS) | 1.8.7 | Bad Telnet Protocol compliance: displays spurious characters. | +| [MUDMaster][14] | 1.3.1 | *UNTESTED* | +| [BlowTorch][15] (Andr) | 1.1.3 | Telnet NOP displays as spurious character. | +| [Mukluk][16] (Andr) | 2015.11.20| Telnet NOP displays as spurious character. Has UTF-8/Emoji | +| | | support. | +| [Gnome-MUD][17] (Unix) | 0.11.2 | Telnet handshake errors. First (only) attempt at logging in | +| | | fails. | +| [Spyrit][18] | 0.4 | No MXP, OOB support. | +| [JamochaMUD][19] | 5.2 | Does not support ANSI within MXP text. | +| [DuckClient][20] (Chrome) | 4.2 | No MXP support. Displays Telnet Go-Ahead and | +| | | WILL SUPPRESS-GO-AHEAD as ù character. Also seems to run | +| | | the `version` command on connection, which will not work in | +| | | `MULTISESSION_MODES` above 1. | +| [KildClient][21] | 2.11.1 | No known issues. | -+----------------------------+-----------+----------------------------------------------------------------+ -| Name | Version | Comments | -+============================+===========+================================================================+ -| `Evennia Webclient`_ | 0.9 | Evennia-specific | -+----------------------------+-----------+----------------------------------------------------------------+ -| `tintin++`_ | 2.0+ | No MXP support | -+----------------------------+-----------+----------------------------------------------------------------+ -| tinyfugue_ | 5.0+ | No UTF-8 support | -+----------------------------+-----------+----------------------------------------------------------------+ -| MUSHclient_ (Win) | 4.94 | NAWS reports full text area | -+----------------------------+-----------+----------------------------------------------------------------+ -| Zmud_ (Win) | 7.21 | *UNTESTED* | -+----------------------------+-----------+----------------------------------------------------------------+ -| Cmud_ (Win) | v3 | *UNTESTED* | -+----------------------------+-----------+----------------------------------------------------------------+ -| Potato_ | 2.0.0b16 | No MXP, MCCP support. Win 32bit does not understand | -| | | "localhost", must use `127.0.0.1`. | -+----------------------------+-----------+----------------------------------------------------------------+ -| Mudlet_ | 3.4+ | No known issues. Some older versions showed <> as html | -| | | under MXP. | -+----------------------------+-----------+----------------------------------------------------------------+ -| SimpleMU_ (Win) | full | Discontinued. NAWS reports pixel size. | -+----------------------------+-----------+----------------------------------------------------------------+ -| Atlantis_ (Mac) | 0.9.9.4 | No known issues. | -+----------------------------+-----------+----------------------------------------------------------------+ -| GMUD_ | 0.0.1 | Can't handle any telnet handshakes. Not recommended. | -+----------------------------+-----------+----------------------------------------------------------------+ -| BeipMU_ (Win) | 3.0.255 | No MXP support. Best to enable "MUD prompt handling", disable | -| | | "Handle HTML tags". | -+----------------------------+-----------+----------------------------------------------------------------+ -| MudRammer_ (IOS) | 1.8.7 | Bad Telnet Protocol compliance: displays spurious characters. | -+----------------------------+-----------+----------------------------------------------------------------+ -| MUDMaster_ | 1.3.1 | *UNTESTED* | -+----------------------------+-----------+----------------------------------------------------------------+ -| BlowTorch_ (Andr) | 1.1.3 | Telnet NOP displays as spurious character. | -+----------------------------+-----------+----------------------------------------------------------------+ -| Mukluk_ (Andr) | 2015.11.20| Telnet NOP displays as spurious character. Has UTF-8/Emoji | -| | | support. | -+----------------------------+-----------+----------------------------------------------------------------+ -| Gnome-MUD_ (Unix) | 0.11.2 | Telnet handshake errors. First (only) attempt at logging in | -| | | fails. | -+----------------------------+-----------+----------------------------------------------------------------+ -| Spyrit_ | 0.4 | No MXP, OOB support. | -+----------------------------+-----------+----------------------------------------------------------------+ -| JamochaMUD_ | 5.2 | Does not support ANSI within MXP text. | -+----------------------------+-----------+----------------------------------------------------------------+ -| DuckClient_ (Chrome) | 4.2 | No MXP support. Displays Telnet Go-Ahead and | -| | | WILL SUPPRESS-GO-AHEAD as ù character. Also seems to run | -| | | the `version` command on connection, which will not work in | -| | | `MULTISESSION_MODES` above 1. | -+----------------------------+-----------+----------------------------------------------------------------+ -| KildClient_ | 2.11.1 | No known issues. | -+----------------------------+-----------+----------------------------------------------------------------+ -.. _Evennia Webclient: ../Components/Webclient.html -.. _tintin++: http://tintin.sourceforge.net/ -.. _tinyfugue: http://tinyfugue.sourceforge.net/ -.. _MUSHclient: http://mushclient.com/ -.. _Zmud: http://forums.zuggsoft.com/index.php?page=4&action=file&file_id=65 -.. _Cmud: http://forums.zuggsoft.com/index.php?page=4&action=category&cat_id=11 -.. _Potato: http://www.potatomushclient.com/ -.. _Mudlet: http://www.mudlet.org/ -.. _SimpleMU: https://archive.org/details/tucows_196173_SimpleMU_MU_Client -.. _Atlantis: http://www.riverdark.net/atlantis/ -.. _GMUD: https://sourceforge.net/projects/g-mud/ -.. _BeipMU: http://www.beipmu.com/ -.. _MudRammer: https://itunes.apple.com/us/app/mudrammer-a-modern-mud-client/id597157072 -.. _MUDMaster: https://itunes.apple.com/us/app/mudmaster/id341160033 -.. _BlowTorch: http://bt.happygoatstudios.com/ -.. _Mukluk: https://play.google.com/store/apps/details?id=com.crap.mukluk -.. _Gnome-MUD: https://github.com/GNOME/gnome-mud -.. _Spyrit: https://spyrit.ierne.eu.org/ -.. _JamochaMUD: http://jamochamud.org/ -.. _DuckClient: http://duckclient.com/ -.. _KildClient: https://www.kildclient.org/ +[1]: ./Webclient +[2]: http://tintin.sourceforge.net/ +[3]: http://tinyfugue.sourceforge.net/ +[4]: https://mushclient.com/ +[5]: http://forums.zuggsoft.com/index.php?page=4&action=file&file_id=65 +[6]: http://forums.zuggsoft.com/index.php?page=4&action=category&cat_id=11 +[7]: https://www.potatomushclient.com/ +[8]: https://www.mudlet.org/ +[9]: https://archive.org/details/tucows_196173_SimpleMU_MU_Client +[10]: https://www.riverdark.net/atlantis/ +[11]: https://sourceforge.net/projects/g-mud/ +[12]: http://www.beipmu.com/ +[13]: https://itunes.apple.com/us/app/mudrammer-a-modern-mud-client/id597157072 +[14]: https://itunes.apple.com/us/app/mudmaster/id341160033 +[15]: https://bt.happygoatstudios.com/ +[16]: https://play.google.com/store/apps/details?id=com.crap.mukluk +[17]: https://github.com/GNOME/gnome-mud +[18]: https://spyrit.ierne.eu.org/ +[19]: https://jamochamud.org/ +[20]: http://duckclient.com/ +[21]: https://www.kildclient.org/ -``` ## Workarounds for client issues: ### Issue: Telnet NOP displays as spurious character. @@ -105,5 +82,3 @@ Workaround: * In-game: Use `@option NOPKEEPALIVE=off` for the session, or use the `/save` parameter to disable it for that Evennia account permanently. * Client-side: Set a gag-type trigger on the NOP character to make it invisible to the client. - - diff --git a/docs/source/Coding-FAQ.md b/docs/source/Coding-FAQ.md index fe5b569266..8b61ca1a18 100644 --- a/docs/source/Coding-FAQ.md +++ b/docs/source/Coding-FAQ.md @@ -7,21 +7,21 @@ exists before answering - maybe you can clarify that answer rather than to make ## Table of Contents -- [Will I run out of dbrefs?](./Coding-FAQ#will-i-run-out-of-dbrefs) -- [Removing default commands](./Coding-FAQ#removing-default-commands) -- [Preventing character from moving based on a condition](./Coding-FAQ#preventing-character-from- +- [Will I run out of dbrefs?](./Coding-FAQ.md#will-i-run-out-of-dbrefs) +- [Removing default commands](./Coding-FAQ.md#removing-default-commands) +- [Preventing character from moving based on a condition](./Coding-FAQ.md#preventing-character-from- moving-based-on-a-condition) -- [Reference initiating object in an EvMenu command](./Coding-FAQ#reference-initiating-object-in-an- +- [Reference initiating object in an EvMenu command](./Coding-FAQ.md#reference-initiating-object-in-an- evmenu-command) -- [Adding color to default Evennia Channels](./Coding-FAQ#adding-color-to-default-evennia-channels) -- [Selectively turn off commands in a room](./Coding-FAQ#selectively-turn-off-commands-in-a-room) -- [Select Command based on a condition](./Coding-FAQ#select-command-based-on-a-condition) -- [Automatically updating code when reloading](./Coding-FAQ#automatically-updating-code-when- +- [Adding color to default Evennia Channels](./Coding-FAQ.md#adding-color-to-default-evennia-channels) +- [Selectively turn off commands in a room](./Coding-FAQ.md#selectively-turn-off-commands-in-a-room) +- [Select Command based on a condition](./Coding-FAQ.md#select-command-based-on-a-condition) +- [Automatically updating code when reloading](./Coding-FAQ.md#automatically-updating-code-when- reloading) -- [Changing all exit messages](./Coding-FAQ#changing-all-exit-messages) -- [Add parsing with the "to" delimiter](./Coding-FAQ#add-parsing-with-the-to-delimiter) -- [Store last used session IP address](./Coding-FAQ#store-last-used-session-ip-address) -- [Use wide characters with EvTable](./Coding-FAQ#non-latin-characters-in-evtable) +- [Changing all exit messages](./Coding-FAQ.md#changing-all-exit-messages) +- [Add parsing with the "to" delimiter](./Coding-FAQ.md#add-parsing-with-the-to-delimiter) +- [Store last used session IP address](./Coding-FAQ.md#store-last-used-session-ip-address) +- [Use wide characters with EvTable](./Coding-FAQ.md#non-latin-characters-in-evtable) ## Will I run out of dbrefs? **Q:** The `#dbref` of a database object is ever-increasing. Evennia doesn't allow you to change or @@ -34,12 +34,12 @@ still using Evennia at that point and has this concern, get back to us and we ca dbref reuse then. ## Removing default commands -**Q:** How does one *remove* (not replace) e.g. the default `get` [Command](./Commands) from the -Character [Command Set](./Command-Sets)? +**Q:** How does one *remove* (not replace) e.g. the default `get` [Command](./Commands.md) from the +Character [Command Set](./Command-Sets.md)? **A:** Go to `mygame/commands/default_cmdsets.py`. Find the `CharacterCmdSet` class. It has one method named `at_cmdset_creation`. At the end of that method, add the following line: -`self.remove(default_cmds.CmdGet())`. See the [Adding Commands Tutorial](./Adding-Command-Tutorial) +`self.remove(default_cmds.CmdGet())`. See the [Adding Commands Tutorial](./Adding-Command-Tutorial.md) for more info. ## Preventing character from moving based on a condition @@ -47,7 +47,7 @@ for more info. combat, immobilized, etc.) **A:** The `at_before_move` hook is called by Evennia just before performing any move. If it returns -`False`, the move is aborted. Let's say we want to check for an [Attribute](./Attributes) `cantmove`. +`False`, the move is aborted. Let's say we want to check for an [Attribute](./Attributes.md) `cantmove`. Add the following code to the `Character` class: ```python @@ -63,7 +63,7 @@ def at_before_move(self, destination): **Q:** An object has a Command on it starts up an EvMenu instance. How do I capture a reference to that object for use in the menu? -**A:** When an [EvMenu](./EvMenu) is started, the menu object is stored as `caller.ndb._menutree`. +**A:** When an [EvMenu](./EvMenu.md) is started, the menu object is stored as `caller.ndb._menutree`. This is a good place to store menu-specific things since it will clean itself up when the menu closes. When initiating the menu, any additional keywords you give will be available for you as properties on this menu object: @@ -112,7 +112,7 @@ CHANNEL_COLORS`. **Q:** I want certain commands to turn off in a given room. They should still work normally for staff. -**A:** This is done using a custom cmdset on a room [locked with the 'call' lock type](./Locks). Only +**A:** This is done using a custom cmdset on a room [locked with the 'call' lock type](./Locks.md). Only if this lock is passed will the commands on the room be made available to an object inside it. Here is an example of a room where certain commands are disabled for non-staff: @@ -153,7 +153,7 @@ superusers). command to only be available on a full moon, from midnight to three in-game time. **A:** This is easiest accomplished by putting the "werewolf" command on the Character as normal, -but to [lock](./Locks) it with the "cmd" type lock. Only if the "cmd" lock type is passed will the +but to [lock](./Locks.md) it with the "cmd" type lock. Only if the "cmd" lock type is passed will the command be available. ```python @@ -168,8 +168,8 @@ class CmdWerewolf(Command): def func(self): # ... ``` -Add this to the [default cmdset as usual](./Adding-Command-Tutorial). The `is_full_moon` [lock -function](Locks#lock-functions) does not yet exist. We must create that: +Add this to the [default cmdset as usual](./Adding-Command-Tutorial.md). The `is_full_moon` [lock +function](./Locks.md#lock-functions) does not yet exist. We must create that: ```python # in mygame/server/conf/lockfuncs.py diff --git a/docs/source/Coding-Introduction.md b/docs/source/Coding-Introduction.md index 6a072b1516..88232b591f 100644 --- a/docs/source/Coding-Introduction.md +++ b/docs/source/Coding-Introduction.md @@ -10,7 +10,7 @@ Here are some pointers to get you going. Evennia is developed using Python. Even if you are more of a designer than a coder, it is wise to learn how to read and understand basic Python code. If you are new to Python, or need a refresher, -take a look at our two-part [Python introduction](./Python-basic-introduction). +take a look at our two-part [Python introduction](./Python-basic-introduction.md). ### Explore Evennia interactively @@ -31,11 +31,11 @@ This will open an Evennia-aware python shell (using ipython). From within this s evennia. That is, enter `evennia.` and press the `` key. This will show you all the resources made -available at the top level of Evennia's "flat API". See the [flat API](./Evennia-API) page for more +available at the top level of Evennia's "flat API". See the [flat API](./Evennia-API.md) page for more info on how to explore it efficiently. You can complement your exploration by peeking at the sections of the much more detailed -[Developer Central](./Developer-Central). The [Tutorials](./Tutorials) section also contains a growing collection +[Developer Central](./Developer-Central.md). The [Tutorials](./Tutorials.md) section also contains a growing collection of system- or implementation-specific help. ### Use a python syntax checker @@ -52,7 +52,7 @@ using such a checker can be a good start to weed out the simple problems. ### Plan before you code -Before you start coding away at your dream game, take a look at our [Game Planning](./Game-Planning) +Before you start coding away at your dream game, take a look at our [Game Planning](./Game-Planning.md) page. It might hopefully help you avoid some common pitfalls and time sinks. ### Code in your game folder, not in the evennia/ repository @@ -64,7 +64,7 @@ it out into your game folder and edit it there. If you find that Evennia doesn't support some functionality you need, make a [Feature Request](github:issue) about it. Same goes for [bugs](github:issue). If you add features or fix bugs -yourself, please consider [Contributing](./Contributing) your changes upstream! +yourself, please consider [Contributing](./Contributing.md) your changes upstream! ### Learn to read tracebacks diff --git a/docs/source/Coding-Utils.md b/docs/source/Coding-Utils.md index 7ec359aecd..e4f1862dbd 100644 --- a/docs/source/Coding-Utils.md +++ b/docs/source/Coding-Utils.md @@ -29,13 +29,13 @@ If you need to search for objects in a code module you can use the functions in obj = search_object(objname) ``` -- [evennia.search_account](../wiki/evennia.accounts.manager#accountdbmanagersearch_account) -- [evennia.search_object](../wiki/evennia.objects.manager#objectdbmanagersearch_object) -- [evennia.search_object_by_tag](../wiki/evennia.utils.search#search_object_by_tag) -- [evennia.search_script](../wiki/evennia.scripts.manager#scriptdbmanagersearch_script) -- [evennia.search_channel](../wiki/evennia.comms.managers#channeldbmanagersearch_channel) -- [evennia.search_message](../wiki/evennia.comms.managers#msgmanagersearch_message) -- [evennia.search_help](../wiki/evennia.help.manager#helpentrymanagersearch_help) +- [evennia.search_account](evennia.accounts.manager.AccountDBManager.search_account) +- [evennia.search_object](evennia.objects.manager.ObjectDBManager.search_object) +- [evennia.search_tag](evennia.utils.search.search_tag) +- [evennia.search_script](evennia.scripts.manager.ScriptDBManager.search_script) +- [evennia.search_channel](evennia.comms.managers.ChannelDBManager.search_channel) +- [evennia.search_message](evennia.comms.managers.MsgManager.search_message) +- [evennia.search_help](evennia.utils.search.search_help_entry) Note that these latter methods will always return a `list` of results, even if the list has one or zero entries. @@ -50,12 +50,12 @@ entities directly in code (for example when defining new create commands). myobj = evennia.create_objects("game.gamesrc.objects.myobj.MyObj", key="MyObj") ``` -- [evennia.create_account](../wiki/evennia.utils.create#create_account) -- [evennia.create_object](../wiki/evennia.utils.create#create_object) -- [evennia.create_script](../wiki/evennia.utils.create#create_script) -- [evennia.create_channel](../wiki/evennia.utils.create#create_channel) -- [evennia.create_help_entry](../wiki/evennia.utils.create#create_help_entry) -- [evennia.create_message](../wiki/evennia.utils.create#create_message) +- [evennia.create_account](create_account) +- [evennia.create_object](create_object) +- [evennia.create_script](create_script) +- [evennia.create_channel](create_channel) +- [evennia.create_help_entry](create_help_entry) +- [evennia.create_message](create_message) Each of these create-functions have a host of arguments to further customize the created entity. See `evennia/utils/create.py` for more information. @@ -181,13 +181,13 @@ number of seconds. This is a very light wrapper over a Twisted non-persistently, which means that if the server is `@reload`ed before the delay is over, the callback will never run (the server forgets it). If setting `persistent` to True, the delay will be stored in the database and survive a `@reload` - but for this to work it is susceptible to the same -limitations incurred when saving to an [Attribute](./Attributes). +limitations incurred when saving to an [Attribute](./Attributes.md). The `deferred` return object can usually be ignored, but calling its `.cancel()` method will abort the delay prematurely. `utils.delay` is the lightest form of delayed call in Evennia. For other way to create time-bound -tasks, see the [TickerHandler](./TickerHandler) and [Scripts](./Scripts). +tasks, see the [TickerHandler](./TickerHandler.md) and [Scripts](./Scripts.md). > Note that many delayed effects can be achieved without any need for an active timer. For example if you have a trait that should recover a point every 5 seconds you might just need its value when @@ -203,7 +203,7 @@ classes, instances or python-paths-to-classes. Note that Python code should usually work with [duck typing](http://en.wikipedia.org/wiki/Duck_typing). But in Evennia's case it can sometimes be useful -to check if an object inherits from a given [Typeclass](./Typeclasses) as a way of identification. Say +to check if an object inherits from a given [Typeclass](./Typeclasses.md) as a way of identification. Say for example that we have a typeclass *Animal*. This has a subclass *Felines* which in turn has a subclass *HouseCat*. Maybe there are a bunch of other animal types too, like horses and dogs. Using `inherits_from` will allow you to check for all animals in one go: @@ -274,10 +274,10 @@ need to send byte-data over the wire, `to_str` is the only one you'll need. The difference from Python's in-built `str()` and `bytes()` operators are that the Evennia ones makes use of the `ENCODINGS` setting and will try very hard to never raise a traceback but instead echo errors through logging. See -[here](./Text-Encodings) for more info. +[here](./Text-Encodings.md) for more info. ### Ansi Coloring Tools -- [evennia.ansi](api:evennia.utils.ansi) +- [evennia.ansi](evennia.utils.ansi) ## Display utilities ### Making ascii tables diff --git a/docs/source/Command-Cooldown.md b/docs/source/Command-Cooldown.md index cd134c5eb1..c150a39c62 100644 --- a/docs/source/Command-Cooldown.md +++ b/docs/source/Command-Cooldown.md @@ -9,7 +9,7 @@ a while. Such effects are called *cooldowns*. This page exemplifies a very resource-efficient way to do cooldowns. A more 'active' way is to use asynchronous delays as in the [command duration -tutorial](Command-Duration#Blocking-Commands), the two might be useful to +tutorial](./Command-Duration.md#blocking-commands), the two might be useful to combine if you want to echo some message to the user after the cooldown ends. ## Non-persistent cooldown @@ -88,7 +88,7 @@ database, you need to use the caster for the storage. self.caller.db.firestorm_lastcast = now ``` -Since we are storing as an [Attribute](./Attributes), we need to identify the +Since we are storing as an [Attribute](./Attributes.md), we need to identify the variable as `firestorm_lastcast` so we are sure we get the right one (we'll likely have other skills with cooldowns after all). But this method of using cooldowns also has the advantage of working *between* commands - you can diff --git a/docs/source/Command-Duration.md b/docs/source/Command-Duration.md index 903fad30d1..8a6bee7732 100644 --- a/docs/source/Command-Duration.md +++ b/docs/source/Command-Duration.md @@ -2,7 +2,7 @@ Before reading this tutorial, if you haven't done so already, you might want to -read [the documentation on commands](./Commands) to get a basic understanding of +read [the documentation on commands](./Commands.md) to get a basic understanding of how commands work in Evennia. In some types of games a command should not start and finish immediately. @@ -40,7 +40,7 @@ class CmdTest(Command): > Important: The `yield` functionality will *only* work in the `func` method of > Commands. It only works because Evennia has especially > catered for it in Commands. If you want the same functionality elsewhere you -> must use the [interactive decorator](./Async-Process#The-@interactive-decorator). +> must use the [interactive decorator](./Async-Process.md#the-interactive-decorator). The important line is the `yield 10`. It tells Evennia to "pause" the command and to wait for 10 seconds to execute the rest. If you add this command and @@ -187,7 +187,7 @@ start crafting a shield at the same time, or if you just did a huge power-swing should not be able to do it again immediately. The simplest way of implementing blocking is to use the technique covered in the [Command -Cooldown](Command-Cooldown) tutorial. In that tutorial we implemented cooldowns by having the +Cooldown](./Command-Cooldown.md) tutorial. In that tutorial we implemented cooldowns by having the Command store the current time. Next time the Command was called, we compared the current time to the stored time to determine if enough time had passed for a renewed use. This is a *very* efficient, reliable and passive solution. The drawback is that there is nothing to tell the Player diff --git a/docs/source/Command-Prompt.md b/docs/source/Command-Prompt.md index 47db5d62f4..bf99b5ddc6 100644 --- a/docs/source/Command-Prompt.md +++ b/docs/source/Command-Prompt.md @@ -21,7 +21,7 @@ You can combine the sending of normal text with the sending (updating of the pro self.msg("This is a text", prompt="This is a prompt") ``` -You can update the prompt on demand, this is normally done using [OOB](./OOB)-tracking of the relevant +You can update the prompt on demand, this is normally done using [OOB](./OOB.md)-tracking of the relevant Attributes (like the character's health). You could also make sure that attacking commands update the prompt when they cause a change in health, for example. diff --git a/docs/source/Command-Sets.md b/docs/source/Command-Sets.md index be5c452119..ab4d56a446 100644 --- a/docs/source/Command-Sets.md +++ b/docs/source/Command-Sets.md @@ -1,7 +1,7 @@ # Command Sets -Command Sets are intimately linked with [Commands](./Commands) and you should be familiar with +Command Sets are intimately linked with [Commands](./Commands.md) and you should be familiar with Commands before reading this page. The two pages were split for ease of reading. A *Command Set* (often referred to as a CmdSet or cmdset) is the basic unit for storing one or more @@ -11,7 +11,7 @@ classes in a command set is the way to make commands available to use in your ga When storing a CmdSet on an object, you will make the commands in that command set available to the object. An example is the default command set stored on new Characters. This command set contains all the useful commands, from `look` and `inventory` to `@dig` and `@reload` -([permissions](./Locks#Permissions) then limit which players may use them, but that's a separate +([permissions](./Locks.md#permissions) then limit which players may use them, but that's a separate topic). When an account enters a command, cmdsets from the Account, Character, its location, and elsewhere @@ -26,7 +26,7 @@ on. The tutorial world included with Evennia showcases a dark room that replaces commands with its own versions because the Character cannot see. If you want a quick start into defining your first commands and using them with command sets, you -can head over to the [Adding Command Tutorial](./Adding-Command-Tutorial) which steps through things +can head over to the [Adding Command Tutorial](./Adding-Command-Tutorial.md) which steps through things without the explanations. ## Defining Command Sets @@ -112,11 +112,11 @@ back even if all other cmdsets fail or are removed. It is always persistent and by `cmdset.delete()`. To remove a default cmdset you must explicitly call `cmdset.remove_default()`. Command sets are often added to an object in its `at_object_creation` method. For more examples of -adding commands, read the [Step by step tutorial](./Adding-Command-Tutorial). Generally you can +adding commands, read the [Step by step tutorial](./Adding-Command-Tutorial.md). Generally you can customize which command sets are added to your objects by using `self.cmdset.add()` or `self.cmdset.add_default()`. -> Important: Commands are identified uniquely by key *or* alias (see [Commands](./Commands)). If any +> Important: Commands are identified uniquely by key *or* alias (see [Commands](./Commands.md)). If any overlap exists, two commands are considered identical. Adding a Command to a command set that already has an identical command will *replace* the previous command. This is very important. You must take this behavior into account when attempting to overload any default Evennia commands with @@ -127,7 +127,7 @@ new one that has a matching alias. There are several extra flags that you can set on CmdSets in order to modify how they work. All are optional and will be set to defaults otherwise. Since many of these relate to *merging* cmdsets, -you might want to read the [Adding and Merging Command Sets](./Command-Sets#adding-and-merging- +you might want to read the [Adding and Merging Command Sets](./Command-Sets.md#adding-and-merging- command-sets) section for some of these to make sense. - `key` (string) - an identifier for the cmdset. This is optional, but should be unique. It is used @@ -138,7 +138,7 @@ dictionary below. - `priority` (int) - This defines the merge order of the merge stack - cmdsets will merge in rising order of priority with the highest priority set merging last. During a merger, the commands from the set with the higher priority will have precedence (just what happens depends on the [merge -type](Command-Sets#adding-and-merging-command-sets)). If priority is identical, the order in the +type](./Command-Sets.md#adding-and-merging-command-sets)). If priority is identical, the order in the merge stack determines preference. The priority value must be greater or equal to `-100`. Most in- game sets should usually have priorities between `0` and `100`. Evennia default sets have priorities as follows (these can be changed if you want a different distribution): @@ -154,7 +154,7 @@ arguments, there is no collision between exits named the same as a channel even differently with certain named cmdsets. If the cmdset to merge with has a `key` matching an entry in `key_mergetype`, it will not be merged according to the setting in `mergetype` but according to the mode in this dict. Please note that this is more complex than it may seem due to the [merge -order](Command-Sets#adding-and-merging-command-sets) of command sets. Please review that section +order](./Command-Sets.md#adding-and-merging-command-sets) of command sets. Please review that section before using `key_mergetype`. - `duplicates` (bool/None default `None`) - this determines what happens when merging same-priority cmdsets containing same-key commands together. The`dupicate` option will *only* apply when merging @@ -195,15 +195,15 @@ priority determines what is used. ## Command Sets Searched -When a user issues a command, it is matched against the [merged](./Command-Sets#adding-and-merging- +When a user issues a command, it is matched against the [merged](./Command-Sets.md#adding-and-merging- command-sets) command sets available to the player at the moment. Which those are may change at any time (such as when the player walks into the room with the `Window` object described earlier). The currently valid command sets are collected from the following sources: -- The cmdsets stored on the currently active [Session](./Sessions). Default is the empty +- The cmdsets stored on the currently active [Session](./Sessions.md). Default is the empty `SessionCmdSet` with merge priority `-20`. -- The cmdsets defined on the [Account](./Accounts). Default is the AccountCmdSet with merge priority +- The cmdsets defined on the [Account](./Accounts.md). Default is the AccountCmdSet with merge priority `-10`. - All cmdsets on the Character/Object (assuming the Account is currently puppeting such a Character/Object). Merge priority `0`. @@ -215,14 +215,14 @@ included if `no_objs` option is active in the merge stack. `no_objs` option is active in the merge stack. - The cmdsets of Exits in the location. Merge priority `+101`. Will not be included if `no_exits` *or* `no_objs` option is active in the merge stack. -- The [channel](./Communications) cmdset containing commands for posting to all channels the account +- The [channel](./Communications.md) cmdset containing commands for posting to all channels the account or character is currently connected to. Merge priority `+101`. Will not be included if `no_channels` option is active in the merge stack. Note that an object does not *have* to share its commands with its surroundings. A Character's cmdsets should not be shared for example, or all other Characters would get multi-match errors just by being in the same room. The ability of an object to share its cmdsets is managed by its `call` -[lock](./Locks). For example, [Character objects](./Objects) defaults to `call:false()` so that any +[lock](./Locks.md). For example, [Character objects](./Objects.md) defaults to `call:false()` so that any cmdsets on them can only be accessed by themselves, not by other objects around them. Another example might be to lock an object with `call:inside()` to only make their commands available to objects inside them, or `cmd:holds()` to make their commands available only if they are held. diff --git a/docs/source/Command-System.md b/docs/source/Command-System.md index 1288202ce5..364d6f09ef 100644 --- a/docs/source/Command-System.md +++ b/docs/source/Command-System.md @@ -1,9 +1,9 @@ # Command System -- [Commands](./Commands) -- [Command Sets](./Command-Sets) -- [Command Auto-help](./Help-System#command-auto-help-system) +- [Commands](./Commands.md) +- [Command Sets](./Command-Sets.md) +- [Command Auto-help](./Help-System.md#command-auto-help-system) See also: -- [Default Command Help](./Default-Command-Help) -- [Adding Command Tutorial](./Adding-Command-Tutorial) \ No newline at end of file +- [Default Command Help](./Default-Commands.md) +- [Adding Command Tutorial](./Adding-Command-Tutorial.md) \ No newline at end of file diff --git a/docs/source/Commands.md b/docs/source/Commands.md index d59ddc0f69..934579acb8 100644 --- a/docs/source/Commands.md +++ b/docs/source/Commands.md @@ -1,14 +1,14 @@ # Commands -Commands are intimately linked to [Command Sets](./Command-Sets) and you need to read that page too to +Commands are intimately linked to [Command Sets](./Command-Sets.md) and you need to read that page too to be familiar with how the command system works. The two pages were split for easy reading. The basic way for users to communicate with the game is through *Commands*. These can be commands directly related to the game world such as *look*, *get*, *drop* and so on, or administrative commands such as *examine* or *@dig*. -The [default commands](./Default-Command-Help) coming with Evennia are 'MUX-like' in that they use @ +The [default commands](./Default-Commands.md) coming with Evennia are 'MUX-like' in that they use @ for admin commands, support things like switches, syntax with the '=' symbol etc, but there is nothing that prevents you from implementing a completely different command scheme for your game. You can find the default commands in `evennia/commands/default`. You should not edit these directly - @@ -16,7 +16,7 @@ they will be updated by the Evennia team as new features are added. Rather you s for inspiration and inherit your own designs from them. There are two components to having a command running - the *Command* class and the [Command -Set](Command-Sets) (command sets were split into a separate wiki page for ease of reading). +Set](./Command-Sets.md) (command sets were split into a separate wiki page for ease of reading). 1. A *Command* is a python class containing all the functioning code for what a command does - for example, a *get* command would contain code for picking up objects. @@ -28,8 +28,8 @@ object in various ways. Consider a "Tree" object with a cmdset defining the comm *chop down*. Or a "Clock" with a cmdset containing the single command *check time*. This page goes into full detail about how to use Commands. To fully use them you must also read the -page detailing [Command Sets](./Command-Sets). There is also a step-by-step [Adding Command -Tutorial](Adding-Command-Tutorial) that will get you started quickly without the extra explanations. +page detailing [Command Sets](./Command-Sets.md). There is also a step-by-step [Adding Command +Tutorial](./Adding-Command-Tutorial.md) that will get you started quickly without the extra explanations. ## Defining Commands @@ -80,15 +80,15 @@ In Evennia there are three types of objects that may call the command. It is im of this since this will also assign appropriate `caller`, `session`, `sessid` and `account` properties on the command body at runtime. Most often the calling type is `Session`. -* A [Session](./Sessions). This is by far the most common case when a user is entering a command in +* A [Session](./Sessions.md). This is by far the most common case when a user is entering a command in their client. - * `caller` - this is set to the puppeted [Object](./Objects) if such an object exists. If no + * `caller` - this is set to the puppeted [Object](./Objects.md) if such an object exists. If no puppet is found, `caller` is set equal to `account`. Only if an Account is not found either (such as before being logged in) will this be set to the Session object itself. - * `session` - a reference to the [Session](./Sessions) object itself. + * `session` - a reference to the [Session](./Sessions.md) object itself. * `sessid` - `sessid.id`, a unique integer identifier of the session. - * `account` - the [Account](./Accounts) object connected to this Session. None if not logged in. -* An [Account](./Accounts). This only happens if `account.execute_cmd()` was used. No Session + * `account` - the [Account](./Accounts.md) object connected to this Session. None if not logged in. +* An [Account](./Accounts.md). This only happens if `account.execute_cmd()` was used. No Session information can be obtained in this case. * `caller` - this is set to the puppeted Object if such an object can be determined (without Session info this can only be determined in `MULTISESSION_MODE=0` or `1`). If no puppet is found, @@ -96,7 +96,7 @@ this is equal to `account`. * `session` - `None*` * `sessid` - `None*` * `account` - Set to the Account object. -* An [Object](./Objects). This only happens if `object.execute_cmd()` was used (for example by an +* An [Object](./Objects.md). This only happens if `object.execute_cmd()` was used (for example by an NPC). * `caller` - This is set to the calling Object in question. * `session` - `None*` @@ -119,10 +119,10 @@ it the following properties: - `caller` - The character BigGuy, in this example. This is a reference to the object executing the command. The value of this depends on what type of object is calling the command; see the previous section. -- `session` - the [Session](./Sessions) Bob uses to connect to the game and control BigGuy (see also +- `session` - the [Session](./Sessions.md) Bob uses to connect to the game and control BigGuy (see also previous section). - `sessid` - the unique id of `self.session`, for quick lookup. -- `account` - the [Account](./Accounts) Bob (see previous section). +- `account` - the [Account](./Accounts.md) Bob (see previous section). - `cmdstring` - the matched key for the command. This would be *look* in our example. - `args` - this is the rest of the string, except the command name. So if the string entered was *look at sword*, `args` would be " *at sword*". Note the space kept - Evennia would correctly @@ -130,7 +130,7 @@ interpret `lookat sword` too. This is useful for things like `/switches` that sh In the `MuxCommand` class used for default commands, this space is stripped. Also see the `arg_regex` property if you want to enforce a space to make `lookat sword` give a command-not-found error. -- `obj` - the game [Object](./Objects) on which this command is defined. This need not be the caller, +- `obj` - the game [Object](./Objects.md) on which this command is defined. This need not be the caller, but since `look` is a common (default) command, this is probably defined directly on *BigGuy* - so `obj` will point to BigGuy. Otherwise `obj` could be an Account or any interactive object with commands defined on it, like in the example of the "check time" command defined on a "Clock" object. @@ -149,7 +149,7 @@ not used, but they could be used to implement alternate help-display systems. - `.client_width()` - Shortcut for getting the client's screen-width. Note that not all clients will truthfully report this value - that case the `settings.DEFAULT_SCREEN_WIDTH` will be returned. -- `.styled_table(*args, **kwargs)` - This returns an [EvTable](api:evennia.utils#module- +- `.styled_table(*args, **kwargs)` - This returns an [EvTable](module- evennia.utils.evtable) styled based on the session calling this command. The args/kwargs are the same as for EvTable, except styling defaults are set. @@ -168,7 +168,7 @@ key can consist of more than one word, like "press button" or "pull left lever". either matches. This is important for merging cmdsets described below. - `aliases` (optional list) - a list of alternate names for the command (`["glance", "see", "l"]`). Same name rules as for `key` applies. -- `locks` (string) - a [lock definition](./Locks), usually on the form `cmd:`. Locks is a +- `locks` (string) - a [lock definition](./Locks.md), usually on the form `cmd:`. Locks is a rather big topic, so until you learn more about locks, stick to giving the lockstring `"cmd:all()"` to make the command available to everyone (if you don't provide a lock string, this will be assigned for you). @@ -180,9 +180,9 @@ by the next command by retrieving `self.caller.ndb.last_cmd`. The next run comma or replace the storage. - `arg_regex` (optional raw string): Used to force the parser to limit itself and tell it when the command-name ends and arguments begin (such as requiring this to be a space or a /switch). This is -done with a regular expression. [See the arg_regex section](./Commands#on-arg_regex) for the details. +done with a regular expression. [See the arg_regex section](./Commands.md#on-arg_regex) for the details. - `auto_help` (optional boolean). Defaults to `True`. This allows for turning off the [auto-help -system](Help-System#command-auto-help-system) on a per-command basis. This could be useful if you +system](./Help-System.md#command-auto-help-system) on a per-command basis. This could be useful if you either want to write your help entries manually or hide the existence of a command from `help`'s generated list. - `is_exit` (bool) - this marks the command as being used for an in-game exit. This is, by default, @@ -218,7 +218,7 @@ from this method will be returned from the execution as a Twisted Deferred. Finally, you should always make an informative [doc string](http://www.python.org/dev/peps/pep-0257/#what-is-a-docstring) (`__doc__`) at the top of your -class. This string is dynamically read by the [Help System](./Help-System) to create the help entry +class. This string is dynamically read by the [Help System](./Help-System.md) to create the help entry for this command. You should decide on a way to format your help and stick to that. Below is how you define a simple alternative "`smile`" command: @@ -276,7 +276,7 @@ default commands thus need to implement `parse()` at all, but can assume the incoming string is already split up and parsed in suitable ways by its parent. Before you can actually use the command in your game, you must now store it -within a *command set*. See the [Command Sets](./Command-Sets) page. +within a *command set*. See the [Command Sets](./Command-Sets.md) page. ### On arg_regex @@ -427,7 +427,7 @@ will show. > Note again that the `yield` keyword does not store state. If the game reloads while waiting for the user to answer, the user will have to start over. It is not a good idea to use `yield` for -important or complex choices, a persistent [EvMenu](./EvMenu) might be more appropriate in this case. +important or complex choices, a persistent [EvMenu](./EvMenu.md) might be more appropriate in this case. ## System commands @@ -457,7 +457,7 @@ display the "Huh?" error message. matches. - User is not allowed to execute the command (`syscmdkeys.CMD_NOPERM`) - Default is to display the "Huh?" error message. -- Channel (`syscmdkeys.CMD_CHANNEL`) - This is a [Channel](./Communications) name of a channel you are +- Channel (`syscmdkeys.CMD_CHANNEL`) - This is a [Channel](./Communications.md) name of a channel you are subscribing to - Default is to relay the command's argument to that channel. Such commands are created by the Comm system on the fly depending on your subscriptions. - New session connection (`syscmdkeys.CMD_LOGINSTART`). This command name should be put in the @@ -484,7 +484,7 @@ work. Normally Commands are created as fixed classes and used without modification. There are however situations when the exact key, alias or other properties is not possible (or impractical) to pre- -code ([Exits](./Commands#Exits) is an example of this). +code ([Exits](./Commands.md#exits) is an example of this). To create a command with a dynamic call signature, first define the command body normally in a class (set your `key`, `aliases` to default values), then use the following call (assuming the command @@ -508,10 +508,10 @@ make your command completely customized at run-time. *Note: This is an advanced topic.* -Exits are examples of the use of a [Dynamic Command](./Commands#Dynamic_Commands). +Exits are examples of the use of a [Dynamic Command](./Commands.md#dynamic-commands). -The functionality of [Exit](./Objects) objects in Evennia is not hard-coded in the engine. Instead -Exits are normal [typeclassed](./Typeclasses) objects that auto-create a [CmdSet](./Commands#CmdSets) on +The functionality of [Exit](./Objects.md) objects in Evennia is not hard-coded in the engine. Instead +Exits are normal [typeclassed](./Typeclasses.md) objects that auto-create a [CmdSet](./Command-Sets.md) on themselves when they load. This cmdset has a single dynamically created Command with the same properties (key, aliases and locks) as the Exit object itself. When entering the name of the exit, this dynamic exit-command is triggered and (after access checks) moves the Character to the exit's @@ -609,9 +609,9 @@ cmdset, ignore. - CmdSets defined on the current account, if caller is a puppeted object. - CmdSets defined on the Session itself. - The active CmdSets of eventual objects in the same location (if any). This includes commands -on [Exits](./Objects#Exits). +on [Exits](./Objects.md#exits). - Sets of dynamically created *System commands* representing available -[Communications](./Communications#Channels). +[Communications](./Communications.md#channels). 7. All CmdSets *of the same priority* are merged together in groups. Grouping avoids order- dependent issues of merging multiple same-prio sets onto lower ones. 8. All the grouped CmdSets are *merged* in reverse priority into one combined CmdSet according to diff --git a/docs/source/Communications.md b/docs/source/Communications.md index dba169650a..3c3056c54f 100644 --- a/docs/source/Communications.md +++ b/docs/source/Communications.md @@ -12,7 +12,7 @@ mimics the API of a `Msg` but has no connection to the database. ## Msg The `Msg` object is the basic unit of communication in Evennia. A message works a little like an -e-mail; it always has a sender (a [Account](./Accounts)) and one or more recipients. The recipients +e-mail; it always has a sender (a [Account](./Accounts.md)) and one or more recipients. The recipients may be either other Accounts, or a *Channel* (see below). You can mix recipients to send the message to both Channels and Accounts if you like. @@ -22,16 +22,16 @@ have 'mailboxes' with the messages they want to keep. ### Properties defined on `Msg` -- `senders` - this is a reference to one or many [Account](./Accounts) or [Objects](./Objects) (normally +- `senders` - this is a reference to one or many [Account](./Accounts.md) or [Objects](./Objects.md) (normally *Characters*) sending the message. This could also be an *External Connection* such as a message coming in over IRC/IMC2 (see below). There is usually only one sender, but the types can also be mixed in any combination. -- `receivers` - a list of target [Accounts](./Accounts), [Objects](./Objects) (usually *Characters*) or +- `receivers` - a list of target [Accounts](./Accounts.md), [Objects](./Objects.md) (usually *Characters*) or *Channels* to send the message to. The types of receivers can be mixed in any combination. - `header` - this is a text field for storing a title or header for the message. - `message` - the actual text being sent. - `date_sent` - when message was sent (auto-created). -- `locks` - a [lock definition](./Locks). +- `locks` - a [lock definition](./Locks.md). - `hide_from` - this can optionally hold a list of objects, accounts or channels to hide this `Msg` from. This relationship is stored in the database primarily for optimization reasons, allowing for quickly post-filter out messages not intended for a given target. There is no in-game methods for @@ -48,16 +48,16 @@ system expecting a `Msg` but when you don't actually want to save anything. ## Channels -Channels are [Typeclassed](./Typeclasses) entities, which mean they can be easily extended and their +Channels are [Typeclassed](./Typeclasses.md) entities, which mean they can be easily extended and their functionality modified. To change which channel typeclass Evennia uses, change settings.BASE_CHANNEL_TYPECLASS. Channels act as generic distributors of messages. Think of them as "switch boards" redistributing `Msg` or `TempMsg` objects. Internally they hold a list of "listening" objects and any `Msg` (or `TempMsg`) sent to the channel will be distributed out to all channel listeners. Channels have -[Locks](./Locks) to limit who may listen and/or send messages through them. +[Locks](./Locks.md) to limit who may listen and/or send messages through them. -The *sending* of text to a channel is handled by a dynamically created [Command](./Commands) that +The *sending* of text to a channel is handled by a dynamically created [Command](./Commands.md) that always have the same name as the channel. This is created for each channel by the global `ChannelHandler`. The Channel command is added to the Account's cmdset and normal command locks are used to determine which channels are possible to write to. When subscribing to a channel, you can @@ -109,5 +109,5 @@ for channel communication (since the default ChannelCommand instead logs to a fi - `aliases` - alternative native names for channels - `desc` - optional description of channel (seen in listings) - `keep_log` (bool) - if the channel should store messages (default) -- `locks` - A [lock definition](./Locks). Channels normally use the access_types `send, control` and +- `locks` - A [lock definition](./Locks.md). Channels normally use the access_types `send, control` and `listen`. \ No newline at end of file diff --git a/docs/source/Connection-Screen.md b/docs/source/Connection-Screen.md index d0b4f37275..bb15919f30 100644 --- a/docs/source/Connection-Screen.md +++ b/docs/source/Connection-Screen.md @@ -20,7 +20,7 @@ Effective, but not very exciting. You will most likely want to change this to be your game. This is simple: 1. Edit `mygame/server/conf/connection_screens.py`. -1. [Reload](./Start-Stop-Reload) Evennia. +1. [Reload](./Start-Stop-Reload.md) Evennia. Evennia will look into this module and locate all *globally defined strings* in it. These strings are used as the text in your connection screen and are shown to the user at startup. If more than @@ -29,8 +29,8 @@ available. ### Commands available at the Connection Screen -You can also customize the [Commands](./Commands) available to use while the connection screen is +You can also customize the [Commands](./Commands.md) available to use while the connection screen is shown (`connect`, `create` etc). These commands are a bit special since when the screen is running the account is not yet logged in. A command is made available at the login screen by adding them to -`UnloggedinCmdSet` in `mygame/commands/default_cmdset.py`. See [Commands](./Commands) and the +`UnloggedinCmdSet` in `mygame/commands/default_cmdset.py`. See [Commands](./Commands.md) and the tutorial section on how to add new commands to a default command set. diff --git a/docs/source/Continuous-Integration.md b/docs/source/Continuous-Integration.md index f6323cc9f3..f4bf7e5199 100644 --- a/docs/source/Continuous-Integration.md +++ b/docs/source/Continuous-Integration.md @@ -27,7 +27,7 @@ Among those you will need: * A Continuous Integration Environment. * I recommend [TeamCity](https://www.jetbrains.com/teamcity/) which has an in-depth [Setup Guide](https://confluence.jetbrains.com/display/TCD8/Installing+and+Configuring+the+TeamCity+Server) -* [Source Control](./Version-Control) +* [Source Control](./Version-Control.md) * This could be Git or SVN or any other available SC. ## Linux TeamCity Setup diff --git a/docs/source/Contributing-Docs.md b/docs/source/Contributing-Docs.md index 491c09eb51..a7236cee9c 100644 --- a/docs/source/Contributing-Docs.md +++ b/docs/source/Contributing-Docs.md @@ -1,34 +1,507 @@ # Contributing to Evennia Docs -```warning:: - The creation of docs pages is still WIP and we are still figuring things out here and there. +```{warning} +This system is still WIP and many things are bound to change! ``` -Contributing to the docs is is like [contributing to the rest of Evennia][contributing]: Check out the branch of Evennia you want to edit the documentation for. Create your -own work-branch, make your changes to files in `evennia/docs/source/` and make a PR for it! +Contributing to the docs is is like [contributing to the rest of Evennia][contributing]: Check out the branch of Evennia +you want to edit the documentation for. Create your own work-branch, make your changes to files +in `evennia/docs/source/` and make a PR for it! The documentation source files are `*.md` (Markdown) files found in `evennia/docs/source/`. Markdown files are simple text files that can be edited with a normal text editor. They can also -contain raw HTML directives (but that is very rarely needed). They primarly use -the [Markdown][commonmark] syntax. See [the syntax section below](#Editing-syntax) for more help. +contain raw HTML directives (but that is very rarely needed). They use +the [Markdown][commonmark] syntax with [MyST extensions][MyST]. -## Source file structure +```{important} +You do _not_ need to be able to test/build the docs locally to contribute a documentation PR. +We'll resolve any issues when we merge and build documentation. If you still want to build +the docs for yourself, instructions are [at the end of this document](#building-the-docs-locally). +``` -For v 0.9.5, the sources are all together under `evennia/docs/source/`. The main files are all -Markdown (`.md`) files. +## Source file structure -Other files and folders: +The sources are organized into several rough categories, with only a few administrative documents +at the root of `evennia/docs/source/`. The folders are named in singular form since they will +primarily be accessed as link refs (e.g. `Component/Accounts`) + +- `source/Components/` are docs describing separate Evennia building blocks, that is, things + that you can import and use. This extends and elaborates on what can be found out by reading + the api docs themselves. Example are documentation for `Accounts`, `Objects` and `Commands`. +- `source/Concepts/` describes how larger-scale features of Evennia hang together - things that + can't easily be broken down into one isolated component. This can be general descriptions of + how Models and Typeclasses interact to the path a message takes from the client to the server + and back. +- `source/Setup/` holds detailed docs on installing, running and maintaining the Evennia server and + the infrastructure around it. +- `source/Coding/` has help on how to interact with, use and navigate the Evennia codebase itself. + This also has non-Evennia-specific help on general development concepts and how to set up a sane + development environment. +- `source/Contribs/` holds documentation specifically for packages in the `evennia/contribs/` folder. + Any contrib-specific tutorials will be found here instead of in `Howtos` +- `source/Howtos/` holds docs that describe how to achieve a specific goal, effect or + result in Evennia. This is often on a tutorial or FAQ form and will refer to the rest of the + documentation for further reading. + - `source/Howtos/Starting/` holds all documents part of the initial tutorial sequence. + + + Other files and folders: - `source/api/` contains the auto-generated API documentation as `.rst` files. Don't edit these - files manually, your changes will be lost. To refer to these files, use `api:` followed by - the Python path, for example `[rpsystem contrib](api:evennia.contrib.rpsystem)`. - - `source/_templates` and `source/_static` should not be modified unless adding a new doc-page + files manually, your changes will be lost. To refer to these files, use `api:` followed by + the Python path, for example `[rpsystem contrib](evennia.contrib.rpsystem)`. + - `source/_templates` and `source/_static` should not be modified unless adding a new doc-page feature or changing the look of the HTML documentation. - `conf.py` holds the Sphinx configuration. It should usually not be modified except to update the Evennia version on a new branch. - -## Building the docs locally + +# Editing syntax + +The format used for Evennia's docs is [Markdown][commonmark-help] (Commonmark). While markdown +supports a few alternative forms for some of these, we try to stick to the below forms for consistency. + +## Italic/Bold + +We generally use underscores for italics and double-asterisks for bold: + +- `_Italic text_` - _Italic text_ +- `**Bold Text**` - **Bold text** + +## Headings + +We use `#` to indicate sections/headings. The more `#` the more of a sub-heading it is (will get +smaller and smaller font). + +- `# Heading` +- `## SubHeading` +- `### SubSubHeading` +- `#### SubSubSubHeading` + +> Don't use the same heading/subheading name more than once in one page. While Markdown +does not prevent it, it will make it impossible to refer to that heading uniquely. +The Evennia documentation preparser will detect this and give you an error. + +## Lists + +One can create both bullet-point lists and numbered lists: + +``` +- first bulletpoint +- second bulletpoint +- third bulletpoint +``` + +- first bulletpoint +- second bulletpoint +- third bulletpoint + +``` +1. Numbered point one +2. Numbered point two +3. Numbered point three +``` + +1. Numbered point one +2. Numbered point two +3. Numbered point three + +## Blockquotes + +A blockquote will create an indented block. It's useful for emphasis and is +added by starting one or more lines with `>`. For 'notes' you can also use +an explicit [Note](#note). + +``` +> This is an important +> thing to remember. +``` + +> Note: This is an important +> thing to remember. + +## Links + +The link syntax is `[linktext](url_or_ref)` - this gives a clickable link [linktext](#links). + +### Internal links + +Most links will be to other pages of the documentation or to Evennia's API docs. Each document +heading can be referenced. The reference always starts with `#`. The heading-name is always +given in lowercase and ignores any non-letters. Spaces in the heading title are replaced with +a single dash `-`. + +As an example, let's assume the following is the contents of a file `Menu-stuff.md`: + +``` +# Menu items + +Some text... + +## A yes/no? example + +Some more text... +``` + +- From _inside the same file_ you can refer to each heading as + + [menus](#menu-items) + [example](#a-yesno-example) + +- From _another file_, you reference them as as + + [menus](Menu-Stuff.md#menu-items) + [example](Menu-Stuff.md#a-yesno-example) + +> It's fine to not include the `.md` file ending in the reference. The Evennia doc-build process +> will correct for this (and also insert any needed relative paths in the reference). + +### API links + +The documentation contains auto-generated documentation for all of Evennia's source code. You +can direct the reader to the sources by just giving the python-path to the location of the +resource under the `evennia/` repository: + + [DefaultObject](evennia.objects.objects.DefaultObject) + +[DefaultObject](evennia.objects.objects.DefaultObject) <- like this! + +Note that you can't refer to files in the `mygame` folder this way. The game folder is generated +dynamically and is not part of the api docs. Refer to the parent classes in `evennia` where possible. + +### External links + +These are links to resources outside of the documentation. We also provide some convenient shortcuts. + +- `[linkname](https://evennia.com)` - link to an external website. +- `[linkname](github:evennia/objects/objects.py)` - this is a shortcut to point to a location in the + official Evennia repository on Github. Note that you must use `/` and give the full file name. By + default this is code in the `master` branch. +- `[linkname](github:develop/evennia/objects.objects.py` - this points to code in the `develop` branch. +- `[make an issue](github:issue)` - this is a shortcut to the Evennia github issue-creation page. + +> Note that if you want to refer to code, it's usually better to [link to the API](#api-links) as +> described above. + +### Urls/References in one place + +Urls can get long and if you are using the same url/reference in many places it can get a +little cluttered. So you can also put the url as a 'footnote' at the end of your document. +You can then refer to it by putting your reference within square brackets `[ ]`. Here's an example: + +``` +This is a [clickable link][mylink]. This is [another link][1]. + +... + + +[mylink]: http://... +[1]: My-Document.md#this-is-a-long-ref + +``` + +This makes the main text a little shorter. + +## Tables + +A table is done like this: + +```` +| heading1 | heading2 | heading3 | +| --- | --- | --- | +| value1 | value2 | value3 | +| | value 4 | | +| value 5 | value 6 | | +```` + +| heading1 | heading2 | heading3 | +| --- | --- | --- | +| value1 | value2 | value3 | +| | value 4 | | +| value 5 | value 6 | | + +As seen, the Markdown syntax can be pretty sloppy (columns don't need to line up) as long as you +include the heading separators and make sure to add the correct number of `|` on every line. + + +## Verbatim text + +It's common to want to mark something to be displayed verbatim - just as written - without any +Markdown parsing. In running text, this is done using backticks (\`), like \`verbatim text\` becomes +`verbatim text`. + +If you want to put the verbatim text on its own line, you can do so easily by simply indenting +it 4 spaces (add empty lines on each side for readability too): + +``` +This is normal text + + This is verbatim text + +This is normal text +``` + +Another way is to use triple-backticks: + +```` +``` +Everything within these backticks will be verbatim. + +``` +```` + +### Code blocks + +A special 'verbatim' case is code examples - we want them to get code-highlighting for readability. +This is done by using the triple-backticks and specify which language we use: + +```` +```python +from evennia import Command +class CmdEcho(Command): + """ + Usage: echo + """ + key = "echo" + def func(self): + self.caller.msg(self.args.strip()) +``` +```` + +```python +from evennia import Command +class CmdEcho(Command): + """ + Usage: echo + """ + key = "echo" + def func(self): + self.caller.msg(self.args.strip()) +``` + +## MyST directives + +Markdown is easy to read and use. But while it does most of what we need, there are some things it's +not quite as expressive as it needs to be. For this we use extended [MyST][MyST] syntax. This is +on the form + +```` +```{directive} any_options_here + +content + +``` +```` + + +#### Note + +This kind of note may pop more than doing a `> Note: ...`. + +```` +```{note} + +This is some noteworthy content that stretches over more than one line to show how the content indents. +Also the important/warning notes indents like this. + +``` +```` + +```{note} + +This is some noteworthy content that stretches over more than one line to show how the content indents. +Also the important/warning notes indents like this. + +``` + +### Important + +This is for particularly important and visible notes. + +```` +```{important} + This is important because it is! +``` + +```` +```{important} + This is important because it is! +``` + +### Warning + +A warning block is used to draw attention to particularly dangerous things, or features easy to +mess up. + +```` +```{warning} + Be careful about this ... +``` +```` + +```{warning} + Be careful about this ... +``` + +### Version changes and deprecations + +These will show up as one-line warnings that suggest an added, changed or deprecated +feature beginning with particular version. + +```` +```{versionadded} 1.0 +``` +```` + +```{versionadded} 1.0 +``` + +```` +```{versionchanged} 1.0 + How the feature changed with this version. +``` +```` + +```{versionchanged} 1.0 + How the feature changed with this version. +``` + +```` +```{deprecated} 1.0 +``` +```` + +```{deprecated} 1.0 +``` + +### Sidebar + +This will display an informative sidebar that floats to the side of regular content. This is useful +for example to remind the reader of some concept relevant to the text. + +```` +```{sidebar} Things to remember + +- There can be bullet lists +- in here. + +Separate sections with + +an empty line. +``` +```` + +```{sidebar} Things to remember + +- There can be bullet lists +- in here. + +Separate sections with + +an empty line. +``` + +Hint: If wanting to make sure to have the next header appear on a row of its own (rather than +squeezed to the left of the sidebar), one can embed a plain HTML string in the markdown like so: + +```html +
+``` + +
+ +### A more flexible code block + +The regular Markdown Python codeblock is usually enough but for more direct control over the style, one +can also use the `{code-block}` directive that takes a set of additional `:options:`: + +```` +```{code-block} python +:linenos: +:emphasize-lines: 1-2,8 +:caption: An example code block +:name: A full code block example + +from evennia import Command +class CmdEcho(Command): + """ + Usage: echo + """ + key = "echo" + def func(self): + self.caller.msg(self.args.strip()) +``` +```` + +```{code-block} python +:linenos: +:emphasize-lines: 1-2,8 +:caption: An example code block +:name: A full code block example + +from evennia import Command +class CmdEcho(Command): + """ + Usage: echo + """ + key = "echo" + def func(self): + self.caller.msg(self.args.strip()) +``` +Here, `:linenos:` turns on line-numbers and `:emphasize-lines:` allows for emphasizing certain lines +in a different color. The `:caption:` shows an instructive text and `:name:` is used to reference +this +block through the link that will appear (so it should be unique for a given document). + + + +### eval-rst directive + +As a last resort, we can also fall back to writing [ReST][ReST] directives directly: + + +```` +```{eval-rst} + + This will be evaluated as ReST. + All content must be indented. + +``` +```` + +Within a ReST block, one must use Restructured Text syntax, which is not the +same as Markdown. + +- Single backticks around text makes it _italic_. +- Double backticks around text makes it `verbatim`. +- A link is written within back-ticks, with an underscore at the end: + + `python `_ + +[Here is a ReST formatting cheat sheet](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html). + +## Code docstrings + +The source code docstrings will be parsed as Markdown. When writing a module docstring, you can use Markdown formatting, +including header levels down to 4th level (`#### SubSubSubHeader`). After the module documentation it's +a good idea to end with four dashes `----`. This will create a visible line between the documentation and the +class/function docs to follow. + +All non-private classes, methods and functions must have a Google-style docstring, as per the +[Evennia coding style guidelines][github:evennia/CODING_STYLE.md]. This will then be correctly formatted +into pretty api docs. + +## Technical + +Evennia leverages [Sphinx][sphinx] with the [MyST][MyST] extension, which allows us +to write our docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github) +rather than Sphinx' normal ReST syntax. The `MyST` parser allows for some extra syntax to +make us able to express more complex displays than plain Markdown can. + +For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon][sphinx-napoleon] +extension to understand our friendly Google-style docstrings used in classes and functions etc. + +# Building the docs locally The sources in `evennia/docs/source/` are built into a documentation using the [Sphinx][sphinx] static generator system. To do this locally you need to use a @@ -82,23 +555,23 @@ initialize a new game with a default database (you don't need to have any server running) - It's recommended that you use a virtualenv. Install your cloned version of Evennia into -by pointing to the repo folder (the one containing `/docs`): + by pointing to the repo folder (the one containing `/docs`): ``` - pip install -e evennia + pip install -e evennia ``` - + - Make sure you are in the parent folder _containing_ your `evennia/` repo (so _two_ levels up from `evennia/docs/`). - Create a new game folder called exactly `gamedir` at the same level as your `evennia` -repo with + repo with ``` evennia --init gamedir ``` -- Then `cd` into it and create a new, empty database. You don't need to start the -game or do any further changes after this. +- Then `cd` into it and create a new, empty database. You don't need to start the + game or do any further changes after this. ``` evennia migrate @@ -141,7 +614,7 @@ well. We won't touch that.) If you for some reason want to use another location of your `gamedir/`, or want it named something else (maybe you already use the name 'gamedir' for your development ...), you can do so by setting the `EVGAMEDIR` environment variable to the absolute path -of your alternative game dir. For example (bash): +of your alternative game dir. For example: ``` EVGAMEDIR=/my/path/to/mygamedir make local @@ -156,7 +629,7 @@ specific official Evennia branches will be built, so you can't use this to build your own testing branch. - All local changes must have been committed to git first, since the versioned -docs are built by looking at the git tree. + docs are built by looking at the git tree. - To build for local checking, run (`mv` stands for "multi-version"): ``` @@ -188,485 +661,14 @@ on `github`. So there is no risk of you releasing your local changes accidentall After deployment finishes, the updated live documentation will be available at https://evennia.github.io/evennia/latest/. -# Editing syntax - -The format used for Evennia's docs is [Markdown][commonmark-help] (Commonmark). While markdown -supports a -few alternative forms for some of these, we try to stick to the below forms for consistency. - -### Italic/Bold - -We generally use underscores for italics and double-asterisks for bold: - -- `_Italic text_` - _Italic text_ -- `**Bold Text**` - **Bold text** - -### Headings - -We use `#` to indicate sections/headings. The more `#` the more of a sub-heading it is (will get -smaller and smaller font). - -- `# Heading` -- `## SubHeading` -- `### SubSubHeading` -- `#### SubSubSubHeading` - -> Don't use the same heading/subheading name more than once in one page. While Markdown -does not prevent it, it will make it impossible to refer to that heading uniquely. -The Evennia documentation preparser will detect this and give you an error. - -### Lists - -One can create both bullet-point lists and numbered lists: - -``` -- first bulletpoint -- second bulletpoint -- third bulletpoint -``` - -- first bulletpoint -- second bulletpoint -- third bulletpoint - -``` -1. Numbered point one -2. Numbered point two -3. Numbered point three -``` - -1. Numbered point one -2. Numbered point two -3. Numbered point three - -### Blockquotes - -A blockquote will create an indented block. It's useful for emphasis and is -added by starting one or more lines with `>`. For 'notes' you can also use -an explicit [Note](#Note). - -``` -> This is an important -> thing to remember. -``` - -> Note: This is an important -> thing to remember. - -### Links - -- `[linktext](url_or_ref)` - gives a clickable link [linktext][linkdemo]. - -The `url_or_ref` can either be a full `http://...` url or an internal _reference_. For example, use -`[my document](My-Document)` to link to the document `evennia/docs/source/My-Document.md`. Avoid -using -full `http://` linking unless really referring to an external resource. - -- `[linktext](ref#heading-name)` - -You can point to sub-sections (headings) in a document by using a single `#` and the name of the -heading, replacing spaces with dashes. So to refer to a heading `## Cool Stuff` inside `My-Document` -would be a link `[cool stuff](My-Document#Cool-Stuff)`. This is why headings must be uniquely named -within on document. - -- `[linktext][linkref]` - refer to a reference defined later in the document. - -Urls can get long and if you are using the same url in many places it can get a little cluttered. So -you can also put the url as a 'footnote' at the end of your document -and refer to it by putting your reference within square brackets `[ ]`. Here's an example: - -``` -This is a [clickable link][mylink]. This is [another link][1]. - -... - - -[mylink]: http://... -[1]: My-Document - -``` - -#### Special references - -The Evennia documentation supports some special reference shortcuts in links: - -##### Github online repository - -- `github:` - a shortcut for the full path to the Evennia repository on github. This must be given -with forward-slashes and include the `.py` file ending. It will refer to the `master` branch by default: - - [link to objects.py](github:evennia/objects/objects.py) - - This will remap to https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py. -- To refer to the `develop` branch, start the url with `develop/`: - - [link to objects.py](github:develop/evennia/objects/objects.py) - -##### API - -- `api:` - references a path in the api documentation. This is specified as a Python-path: - - [link to api for objects.py](api:evennia.objects) - - This will create a link to the auto-generated `evennia/source/api/evennia.objects.rst` document. - - Since api-docs are generated alongside the documentation, this will always be the api docs for - the current version/branch of the docs. - -##### Bug reports/feature request - - -- `github:issue` - links to the github issue selection page, where the user can choose which type of - issue to create. - - If you find a problem, make a [bug report](github:issue)! - - This will generate a link to https://github.com/evennia/evennia/issues/new/choose. - -### Verbatim text - -It's common to want to mark something to be displayed verbatim - just as written - without any -Markdown parsing. In running text, this is done using backticks (\`), like \`verbatim text\` becomes -`verbatim text`. - -If you want to put the verbatim text on its own line, you can do so easily by simply indenting -it 4 spaces (add empty lines on each side for readability too): - -``` -This is normal text - - This is verbatim text - -This is normal text -``` - -Another way is to use triple-backticks: - -```` -``` -Everything within these backticks will be verbatim. - -``` -```` - -### Code blocks - -A special case is code examples - we want them to get code-highlighting for readability. This is -done by using -the triple-backticks and specify which language we use: - -```` -```python - -def a_python_func(x): - return x * x - -``` -```` - -```python - -def a_python_func(x): - return x * x - -``` - -### ReST blocks - -Markdown is easy to read and use. But while it does most of what we need, there are some things it's -not quite as expressive as it needs to be. For this we need to fall back to the [ReST][ReST] markup -language which the documentation system uses under the hood. This is done by specifying `eval_rst` -as the name of the `language` of a literal block: - -```` -```eval_rst - - This will be evaluated as ReST. - All content must be indented. - -``` -```` - -There is also a short-hand form for starting a [ReST directive][ReST-directives] without need for -`eval_rst`: - -```` -```directive:: possible-option - - Content *must* be indented for it to be included in the directive. - - New lines are ignored, empty lines starts a new paragraph. -``` -```` - -Within a ReST block, one must use Restructured Text syntax, which is not the same as Markdown. - -- Single backticks around text makes it _italic_. -- Double backticks around text makes it `verbatim`. -- A link is written within back-ticks, with an underscore at the end: - - `python `_ - -[Here is a ReST formatting cheat sheet](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html). - -Below are examples of ReST-block structures. - -#### Note - -This kind of note may pop more than doing a `> Note: ...`. Contrary to a -[blockquote](#Blockquotes), the end result will not be indented. - -```` -```note:: - - Remember that you have to indent this content for it to be part of the note. - -``` -```` - - -```note:: - - Remember that you have to indent this content for it to be part of the note. - -``` - -#### Important - -This is for particularly important and visible notes. - -```` -```important:: - This is important because it is! -``` - -```` -```important:: - This is important because it is! -``` - -#### Warning - -A warning block is used to draw attention to particularly dangerous things, or features easy to -mess up. - -```` -```warning:: - Be careful about this ... -``` -```` - -```warning:: - Be careful about this ... -``` - -#### Version changes and deprecations - -These will show up as one-line warnings that suggest an added, changed or deprecated -feature beginning with particular version. - -```` -```versionadded:: 1.0 -``` -```` - -```versionadded:: 1.0 -``` - -```` -```versionchanged:: 1.0 - How the feature changed with this version. -``` -```` - -```versionchanged:: 1.0 - How the feature changed with this version. -``` - -```` -```deprecated:: 1.0 -``` -```` - -```deprecated:: 1.0 -``` - -#### Sidebar - -This will display an informative sidebar that floats to the side of regular content. This is useful -for example to remind the reader of some concept relevant to the text. - -```` -```sidebar:: Things to remember - - - There can be bullet lists - - in here. - - Headers: - with indented blocks like this - Will end up: - as full sub-headings in the sidebar. -``` -```` - -```sidebar:: Things to remember - - - There can be bullet lists - - in here. - - Headers: - with indented blocks like this - Will end up: - as full sub-headings in the sidebar. -``` -Remember that for ReST-directives, the content within the triple-backticks _must_ be indented to -some degree or the content will just appear outside of the directive as regular text. - -If wanting to make sure to have the next header appear on a row of its own, one can embed -a plain HTML string in the markdown like so: - -```html -
-``` - -
- -#### Tables - -A table is specified using [ReST table syntax][ReST-tables] (they don't need to be indented): -```` -```eval_rst - -===== ===== ======= -A B A and B -===== ===== ======= -False False False -True False False -False True False -True True True -===== ===== ======= -``` -```` - -```eval_rst - -===== ===== ======= -A B A and B -===== ===== ======= -False False False -True False False -False True False -True True True -===== ===== ======= -``` - -or the more flexible but verbose - -```` -```eval_rst -+------------------------+------------+----------+----------+ -| Header row, column 3 | Header 2 | Header 3 | Header 4 | -| (header rows optional) | | | | -+========================+============+==========+==========+ -| body row 1, column 1 | column 2 | column 3 | column 4 | -+------------------------+------------+----------+----------+ -| body row 2 | ... | ... | | -+------------------------+------------+----------+----------+ -``` -```` - -```eval_rst -+------------------------+------------+----------+----------+ -| Header row, column 3 | Header 2 | Header 3 | Header 4 | -| (header rows optional) | | | | -+========================+============+==========+==========+ -| body row 1, column 1 | column 2 | column 3 | column 4 | -+------------------------+------------+----------+----------+ -| body row 2 | ... | ... | | -+------------------------+------------+----------+----------+ -``` - -#### A more flexible code block - -The regular Markdown Python codeblock is usually enough but for more direct control over the style, one -can also specify the code block explicitly in `ReST` for more flexibility. -It also provides a link to the code block, identified by its name. - - -```` -```code-block:: python - :linenos: - :emphasize-lines: 1-2,8 - :caption: An example code block - :name: A full code block example - - from evennia import Command - class CmdEcho(Command): - """ - Usage: echo - """ - key = "echo" - def func(self): - self.caller.msg(self.args.strip()) -``` -```` - -```code-block:: python - :linenos: - :emphasize-lines: 1-2,8 - :caption: An example code block - :name: A full code block example - - from evennia import Command - class CmdEcho(Command): - """ - Usage: echo - """ - key = "echo" - def func(self): - self.caller.msg(self.args.strip()) -``` -Here, `:linenos:` turns on line-numbers and `:emphasize-lines:` allows for emphasizing certain lines -in a different color. The `:caption:` shows an instructive text and `:name:` is used to reference -this -block through the link that will appear (so it should be unique for a give document). - -> The default markdown syntax will actually generate a code-block ReST instruction like this -> automatically for us behind the scenes. But the automatic generation can't know things like emphasize- -lines or captions since that's not a part of the Markdown specification. - -## Code documentation - -The source code docstrings will be parsed as Markdown. When writing a module docstring, you can use Markdown formatting, -including header levels down to 4th level (`#### SubSubSubHeader`). After the module documentation it's -a good idea to end with four dashes `----`. This will create a visible line between the documentation and the -class/function docs to follow. See for example [the Traits docs](api:evennia.contrib.traits). - -All non-private classes, methods and functions must have a Google-style docstring, as per the -[Evennia coding style guidelines](github:evennia/CODING_STYLE.md). This will then be correctly formatted -into pretty api docs. - -## Technical - -Evennia leverages [Sphinx][sphinx] with the [recommonmark][recommonmark] extension, which allows us -to write our -docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github) rather -than ReST. -The recommonmark extension however also allows us to use ReST selectively in the places were it is -more -expressive than the simpler (but much easier) Markdown. - -For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon][sphinx-napoleon] -extension -to understand our friendly Google-style docstrings used in classes and functions etc. [sphinx]: https://www.sphinx-doc.org/en/master/ -[recommonmark]: https://recommonmark.readthedocs.io/en/latest/index.html +[MyST]: https://myst-parser.readthedocs.io/en/latest/syntax/reference.html [commonmark]: https://spec.commonmark.org/current/ [commonmark-help]: https://commonmark.org/help/ -[sphinx-autodoc]: http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc -[sphinx-napoleon]: http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html +[sphinx-autodoc]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc +[sphinx-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html [getting-started]: Setup/Setup-Quickstart [contributing]: ./Contributing [ReST]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html @@ -676,4 +678,4 @@ to understand our friendly Google-style docstrings used in classes and functions [linkdemo]: #Links [retext]: https://github.com/retext-project/retext [grip]: https://github.com/joeyespo/grip -[pycharm]: https://www.jetbrains.com/pycharm/ +[pycharm]: https://www.jetbrains.com/pycharm/ \ No newline at end of file diff --git a/docs/source/Contributing.md b/docs/source/Contributing.md index a26229fa42..e49f033c4d 100644 --- a/docs/source/Contributing.md +++ b/docs/source/Contributing.md @@ -90,9 +90,9 @@ a new `README.md` file within that directory. amount of game-style-specific code. Assume your code will be applied to a very different game than you had in mind when creating it. * To make the licensing situation clear we assume all contributions are released with the same -[license as Evennia](./Licensing). If this is not possible for some reason, talk to us and we'll +[license as Evennia](./Licensing.md). If this is not possible for some reason, talk to us and we'll handle it on a case-by-case basis. -* Your contribution must be covered by [unit tests](./Unit-Testing). Having unit tests will both help +* Your contribution must be covered by [unit tests](./Unit-Testing.md). Having unit tests will both help make your code more stable and make sure small changes does not break it without it being noticed, it will also help us test its functionality and merge it quicker. If your contribution is a single module, you can add your unit tests to `evennia/contribs/tests.py`. If your contribution is bigger diff --git a/docs/source/Coordinates.md b/docs/source/Coordinates.md index beed340e48..5c5653ffdd 100644 --- a/docs/source/Coordinates.md +++ b/docs/source/Coordinates.md @@ -23,7 +23,7 @@ instance. ## Coordinates as tags The first concept might be the most surprising at first glance: we will create coordinates as -[tags](./Tags). +[tags](./Tags.md). > Why not attributes, wouldn't that be easier? diff --git a/docs/source/Custom-Protocols.md b/docs/source/Custom-Protocols.md index 805e7c4f0c..93d17ca218 100644 --- a/docs/source/Custom-Protocols.md +++ b/docs/source/Custom-Protocols.md @@ -5,9 +5,9 @@ their own custom client protocol.* -A [PortalSession](./Sessions#Portal-and-Server-Sessions) is the basic data object representing an +A [PortalSession](./Sessions.md#portal-and-server-sessions) is the basic data object representing an external -connection to the Evennia [Portal](./Portal-And-Server) -- usually a human player running a mud client +connection to the Evennia [Portal](./Portal-And-Server.md) -- usually a human player running a mud client of some kind. The way they connect (the language the player's client and Evennia use to talk to each other) is called the connection *Protocol*. The most common such protocol for MUD:s is the *Telnet* protocol. All Portal Sessions are stored and managed by the Portal's *sessionhandler*. @@ -27,7 +27,7 @@ You <-> InputFunc ``` -(See the [Message Path](./Messagepath) for the bigger picture of how data flows through Evennia). The +(See the [Message Path](./Messagepath.md) for the bigger picture of how data flows through Evennia). The parts that needs to be customized to make your own custom protocol is the `Protocol + PortalSession` (which translates between data coming in/out over the wire to/from Evennia internal representation) as well as the `InputFunc` (which handles incoming data). @@ -219,11 +219,11 @@ in our case means sending "foo" across the network. ### Receiving data Just because the protocol is there, does not mean Evennia knows what to do with it. An -[Inputfunc](./Inputfuncs) must exist to receive it. In the case of the `text` input exemplified above, +[Inputfunc](./Inputfuncs.md) must exist to receive it. In the case of the `text` input exemplified above, Evennia alredy handles this input - it will parse it as a Command name followed by its inputs. So handle that you need to simply add a cmdset with commands on your receiving Session (and/or the Object/Character it is puppeting). If not you may need to add your own Inputfunc (see the -[Inputfunc](./Inputfuncs) page for how to do this. +[Inputfunc](./Inputfuncs.md) page for how to do this. These might not be as clear-cut in all protocols, but the principle is there. These four basic components - however they are accessed - links to the *Portal Session*, which is the actual common diff --git a/docs/source/Customize-channels.md b/docs/source/Customize-channels.md index 9c755eec4e..67bc381750 100644 --- a/docs/source/Customize-channels.md +++ b/docs/source/Customize-channels.md @@ -106,7 +106,7 @@ Evennia is smart enough to understand that when we type `+something`, `+` is the `something` is the command argument. This will, of course, fail if you have a command beginning by `+` conflicting with the `CmdConnect` key. 4. We have altered some class attributes, like `auto_help`. If you want to know what they do and -why they have changed here, you can check the [documentation on commands](./Commands). +why they have changed here, you can check the [documentation on commands](./Commands.md). 5. In the command body, we begin by extracting the channel name. Remember that this name should be in the command arguments (that is, in `self.args`). Following the same example, if a player enters `+something`, `self.args` should contain `"something"`. We use `search_channel` to see if this diff --git a/docs/source/Default-Command-Help.md b/docs/source/Default-Command-Help.md deleted file mode 100644 index 42601a0a69..0000000000 --- a/docs/source/Default-Command-Help.md +++ /dev/null @@ -1,2538 +0,0 @@ -# Default Command Help - - -> *This page is auto-generated. Do not modify - your changes will be lost. Report problems to the -[issue tracker](https://github.com/evennia/evennia/issues).* - -The full set of default Evennia commands currently contains 92 commands in 9 source -files. Our policy for adding default commands is outlined [here](./Using-MUX-as-a-Standard). More -information about how commands work can be found in the documentation for [Commands](./Commands). - - - -## A-Z - -- [`__unloggedin_look_command`](https://github.com/evennia/evennia/wiki/Default-Command-Help#wiki-`--unloggedin-look-command`-cmdunconnectedlook) - look when in unlogged-in state -- [about](./Default-Command-Help#wiki-about-cmdabout) - show Evennia info -- [access](./Default-Command-Help#wiki-access-cmdaccess) - show your current game access -- [addcom](./Default-Command-Help#wiki-addcom-cmdaddcom) - add a channel alias and/or subscribe to a -channel -- [alias](./Default-Command-Help#wiki-alias-cmdsetobjalias) - adding permanent aliases for object -- [allcom](./Default-Command-Help#wiki-allcom-cmdallcom) - perform admin operations on all channels -- [ban](./Default-Command-Help#wiki-ban-cmdban) - ban an account from the server -- [batchcode](./Default-Command-Help#wiki-batchcode-cmdbatchcode) - build from batch-code file -- [batchcommands](./Default-Command-Help#wiki-batchcommands-cmdbatchcommands) - build from batch- -command file -- [boot](./Default-Command-Help#wiki-boot-cmdboot) - kick an account from the server. -- [cboot](./Default-Command-Help#wiki-cboot-cmdcboot) - kick an account from a channel you control -- [ccreate](./Default-Command-Help#wiki-ccreate-cmdchannelcreate) - create a new channel -- [cdesc](./Default-Command-Help#wiki-cdesc-cmdcdesc) - describe a channel you control -- [cdestroy](./Default-Command-Help#wiki-cdestroy-cmdcdestroy) - destroy a channel you created -- [cemit](./Default-Command-Help#wiki-cemit-cmdcemit) - send an admin message to a channel you control -- [channels](./Default-Command-Help#wiki-channels-cmdchannels) - list all channels available to you -- [charcreate](./Default-Command-Help#wiki-charcreate-cmdcharcreate) - create a new character -- [chardelete](./Default-Command-Help#wiki-chardelete-cmdchardelete) - delete a character - this -cannot be undone! -- [clock](./Default-Command-Help#wiki-clock-cmdclock) - change channel locks of a channel you control -- [cmdsets](./Default-Command-Help#wiki-cmdsets-cmdlistcmdsets) - list command sets defined on an -object -- [color](./Default-Command-Help#wiki-color-cmdcolortest) - testing which colors your client support -- [command](./Default-Command-Help#wiki-command-objmanipcommand) - This is a parent class for some of -the defining objmanip commands -- [connect](./Default-Command-Help#wiki-connect-cmdunconnectedconnect) - connect to the game -- [copy](./Default-Command-Help#wiki-copy-cmdcopy) - copy an object and its properties -- [cpattr](./Default-Command-Help#wiki-cpattr-cmdcpattr) - copy attributes between objects -- [create](./Default-Command-Help#wiki-create-cmdunconnectedcreate) - create a new account account -- [create](./Default-Command-Help#wiki-create-cmdcreate) - create new objects -- [cwho](./Default-Command-Help#wiki-cwho-cmdcwho) - show who is listening to a channel -- [delcom](./Default-Command-Help#wiki-delcom-cmddelcom) - remove a channel alias and/or unsubscribe -from channel -- [desc](./Default-Command-Help#wiki-desc-cmddesc) - describe an object or the current room. -- [destroy](./Default-Command-Help#wiki-destroy-cmddestroy) - permanently delete objects -- [dig](./Default-Command-Help#wiki-dig-cmddig) - build new rooms and connect them to the current -location -- [drop](./Default-Command-Help#wiki-drop-cmddrop) - drop something -- [emit](./Default-Command-Help#wiki-emit-cmdemit) - admin command for emitting message to multiple -objects -- [examine](./Default-Command-Help#wiki-examine-cmdexamine) - get detailed information about an object -- [find](./Default-Command-Help#wiki-find-cmdfind) - search the database for objects -- [force](./Default-Command-Help#wiki-force-cmdforce) - forces an object to execute a command -- [get](./Default-Command-Help#wiki-get-cmdget) - pick up something -- [give](./Default-Command-Help#wiki-give-cmdgive) - give away something to someone -- [help](./Default-Command-Help#wiki-help-cmdunconnectedhelp) - get help when in unconnected-in state -- [help](./Default-Command-Help#wiki-help-cmdhelp) - View help or a list of topics -- [home](./Default-Command-Help#wiki-home-cmdhome) - move to your character's home location -- [ic](./Default-Command-Help#wiki-ic-cmdic) - control an object you have permission to puppet -- [inventory](./Default-Command-Help#wiki-inventory-cmdinventory) - view inventory -- [irc2chan](./Default-Command-Help#wiki-irc2chan-cmdirc2chan) - Link an evennia channel to an -external IRC channel -- [link](./Default-Command-Help#wiki-link-cmdlink) - link existing rooms together with exits -- [lock](./Default-Command-Help#wiki-lock-cmdlock) - assign a lock definition to an object -- [look](./Default-Command-Help#wiki-look-cmdlook) - look at location or object -- [look](./Default-Command-Help#wiki-look-cmdooclook) - look while out-of-character -- [mvattr](./Default-Command-Help#wiki-mvattr-cmdmvattr) - move attributes between objects -- [name](./Default-Command-Help#wiki-name-cmdname) - change the name and/or aliases of an object -- [nick](./Default-Command-Help#wiki-nick-cmdnick) - define a personal alias/nick by defining a string -to -- [objects](./Default-Command-Help#wiki-objects-cmdobjects) - statistics on objects in the database -- [ooc](./Default-Command-Help#wiki-ooc-cmdooc) - stop puppeting and go ooc -- [open](./Default-Command-Help#wiki-open-cmdopen) - open a new exit from the current room -- [option](./Default-Command-Help#wiki-option-cmdoption) - Set an account option -- [page](./Default-Command-Help#wiki-page-cmdpage) - send a private message to another account -- [password](./Default-Command-Help#wiki-password-cmdpassword) - change your password -- [perm](./Default-Command-Help#wiki-perm-cmdperm) - set the permissions of an account/object -- [pose](./Default-Command-Help#wiki-pose-cmdpose) - strike a pose -- [py](./Default-Command-Help#wiki-py-cmdpy) - execute a snippet of python code -- [quell](./Default-Command-Help#wiki-quell-cmdquell) - use character's permissions instead of -account's -- [quit](./Default-Command-Help#wiki-quit-cmdunconnectedquit) - quit when in unlogged-in state -- [quit](./Default-Command-Help#wiki-quit-cmdquit) - quit the game -- [reload](./Default-Command-Help#wiki-reload-cmdreload) - reload the server -- [reset](./Default-Command-Help#wiki-reset-cmdreset) - reset and reboot the server -- [rss2chan](./Default-Command-Help#wiki-rss2chan-cmdrss2chan) - link an evennia channel to an -external RSS feed -- [say](./Default-Command-Help#wiki-say-cmdsay) - speak as your character -- [script](./Default-Command-Help#wiki-script-cmdscript) - attach a script to an object -- [scripts](./Default-Command-Help#wiki-scripts-cmdscripts) - list and manage all running scripts -- [server](./Default-Command-Help#wiki-server-cmdserverload) - show server load and memory statistics -- [service](./Default-Command-Help#wiki-service-cmdservice) - manage system services -- [sessions](./Default-Command-Help#wiki-sessions-cmdsessions) - check your connected session(s) -- [set](./Default-Command-Help#wiki-set-cmdsetattribute) - set attribute on an object or account -- [setdesc](./Default-Command-Help#wiki-setdesc-cmdsetdesc) - describe yourself -- [sethelp](./Default-Command-Help#wiki-sethelp-cmdsethelp) - Edit the help database. -- [sethome](./Default-Command-Help#wiki-sethome-cmdsethome) - set an object's home location -- [shutdown](./Default-Command-Help#wiki-shutdown-cmdshutdown) - stop the server completely -- [spawn](./Default-Command-Help#wiki-spawn-cmdspawn) - spawn objects from prototype -- [style](./Default-Command-Help#wiki-style-cmdstyle) - In-game style options -- [tag](./Default-Command-Help#wiki-tag-cmdtag) - handles the tags of an object -- [tel](./Default-Command-Help#wiki-tel-cmdteleport) - teleport object to another location -- [time](./Default-Command-Help#wiki-time-cmdtime) - show server time statistics -- [tunnel](./Default-Command-Help#wiki-tunnel-cmdtunnel) - create new rooms in cardinal directions -only -- [typeclass](./Default-Command-Help#wiki-typeclass-cmdtypeclass) - set or change an object's -typeclass -- [unban](./Default-Command-Help#wiki-unban-cmdunban) - remove a ban from an account -- [unlink](./Default-Command-Help#wiki-unlink-cmdunlink) - remove exit-connections between rooms -- [userpassword](./Default-Command-Help#wiki-userpassword-cmdnewpassword) - change the password of an -account -- [wall](./Default-Command-Help#wiki-wall-cmdwall) - make an announcement to all -- [whisper](./Default-Command-Help#wiki-whisper-cmdwhisper) - Speak privately as your character to -another -- [who](./Default-Command-Help#wiki-who-cmdwho) - list who is currently online -- [wipe](./Default-Command-Help#wiki-wipe-cmdwipe) - clear all attributes from an object - -## A-Z by source file - -- [account.py](./Default-Command-Help#accountpy) -- [admin.py](./Default-Command-Help#adminpy) -- [batchprocess.py](./Default-Command-Help#batchprocesspy) -- [building.py](./Default-Command-Help#buildingpy) -- [comms.py](./Default-Command-Help#commspy) -- [general.py](./Default-Command-Help#generalpy) -- [help.py](./Default-Command-Help#helppy) -- [system.py](./Default-Command-Help#systempy) -- [unloggedin.py](./Default-Command-Help#unloggedinpy) - -## Command details - -These are generated from the auto-documentation and are ordered by their source file location in -[evennia/commands/default/](https://github.com/evennia/evennia/tree/master/evennia/commands/default/) - - -### `account.py` - -[View account.py source](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py) - - -#### charcreate (CmdCharCreate) -``` - create a new character - - Usage: - charcreate [= desc] - - Create a new character, optionally giving it a description. You - may use upper-case letters in the name - you will nevertheless - always be able to access your character using lower-case letters - if you want. -``` -- **key:** *charcreate* -- **aliases:** -- **[locks](./Locks):** *"cmd:pperm(Player)"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdCharCreate` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### chardelete (CmdCharDelete) -``` - delete a character - this cannot be undone! - - Usage: - chardelete - - Permanently deletes one of your characters. -``` -- **key:** *chardelete* -- **aliases:** -- **[locks](./Locks):** *"cmd:pperm(Player)"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdCharDelete` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### color (CmdColorTest) -``` - testing which colors your client support - - Usage: - color ansi||xterm256 - - Prints a color map along with in-mud color codes to use to produce - them. It also tests what is supported in your client. Choices are - 16-color ansi (supported in most muds) or the 256-color xterm256 - standard. No checking is done to determine your client supports - color - if not you will see rubbish appear. -``` -- **key:** *color* -- **aliases:** -- **[locks](./Locks):** *"cmd:all()"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdColorTest` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### ic (CmdIC) -``` - control an object you have permission to puppet - - Usage: - ic - - Go in-character (IC) as a given Character. - - This will attempt to "become" a different object assuming you have - the right to do so. Note that it's the ACCOUNT character that puppets - characters/objects and which needs to have the correct permission! - - You cannot become an object that is already controlled by another - account. In principle can be any in-game object as long - as you the account have access right to puppet it. -``` -- **key:** *ic* -- **aliases:** *puppet* -- **[locks](./Locks):** *"cmd:all()"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdIC` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### look (CmdOOCLook) -``` - look while out-of-character - - Usage: - look - - Look in the ooc state. -``` -- **key:** *look* -- **aliases:** *l*, *ls* -- **[locks](./Locks):** *"cmd:all()"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdOOCLook` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### ooc (CmdOOC) -``` - stop puppeting and go ooc - - Usage: - ooc - - Go out-of-character (OOC). - - This will leave your current character and put you in a incorporeal OOC state. -``` -- **key:** *ooc* -- **aliases:** *unpuppet* -- **[locks](./Locks):** *"cmd:pperm(Player)"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdOOC` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### option (CmdOption) -``` - Set an account option - - Usage: - option[/save] [name = value] - - Switches: - save - Save the current option settings for future logins. - clear - Clear the saved options. - - This command allows for viewing and setting client interface - settings. Note that saved options may not be able to be used if - later connecting with a client with different capabilities. -``` -- **key:** *option* -- **aliases:** *options* -- **[locks](./Locks):** *"cmd:all()"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdOption` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### password (CmdPassword) -``` - change your password - - Usage: - password = - - Changes your password. Make sure to pick a safe one. -``` -- **key:** *password* -- **aliases:** -- **[locks](./Locks):** *"cmd:pperm(Player)"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdPassword` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### quell (CmdQuell) -``` - use character's permissions instead of account's - - Usage: - quell - unquell - - Normally the permission level of the Account is used when puppeting a - Character/Object to determine access. This command will switch the lock - system to make use of the puppeted Object's permissions instead. This is - useful mainly for testing. - Hierarchical permission quelling only work downwards, thus an Account cannot - use a higher-permission Character to escalate their permission level. - Use the unquell command to revert back to normal operation. -``` -- **key:** *quell* -- **aliases:** *unquell* -- **[locks](./Locks):** *"cmd:pperm(Player)"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdQuell` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://gi -thub.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### quit (CmdQuit) -``` - quit the game - - Usage: - quit - - Switch: - all - disconnect all connected sessions - - Gracefully disconnect your current session from the - game. Use the /all switch to disconnect from all sessions. -``` -- **key:** *quit* -- **aliases:** -- **[locks](./Locks):** *"cmd:all()"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdQuit` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultAccount'* of class `AccountCmdSet` in [cmdset_account.py](https://gi -thub.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_account.py). - - -#### sessions (CmdSessions) -``` - check your connected session(s) - - Usage: - sessions - - Lists the sessions currently connected to your account. -``` -- **key:** *sessions* -- **aliases:** -- **[locks](./Locks):** *"cmd:all()"* -- **[`help_category`](./Help-System):** *"General"* -- **Source:** class `CmdSessions` in -[account.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/account.py). -Belongs to command set *'DefaultSession'* of class `SessionCmdSet` in [cmdset_session.py](https://github.com/evennia/evennia/tree/master/evennia/commands/default/cmdset_session.py). - - -#### style (CmdStyle) -``` - In-game style options - - Usage: - style - style