Fixes to auto-link remapper

This commit is contained in:
Griatch 2020-07-12 18:10:13 +02:00
parent 7eab265994
commit 5177efe129
17 changed files with 74 additions and 2740 deletions

View file

@ -56,7 +56,7 @@ _multiversion-check-env:
_clean_api_index: _clean_api_index:
rm source/api/* rm source/api/*
# remove supervluous 'module' and 'package' text from api headers # remove superfluous 'module' and 'package' text from api headers
_reformat_apidoc_headers: _reformat_apidoc_headers:
for f in source/api/*.rst; do\ for f in source/api/*.rst; do\
perl -pi -e 's/(module|package)$$// if $$. == 1' $$f ;\ perl -pi -e 's/(module|package)$$// if $$. == 1' $$f ;\
@ -71,7 +71,7 @@ _multiversion-autodoc-index:
make _clean_api_index make _clean_api_index
@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) SPHINX_APIDOC_OPTIONS=$(SPHINXAPIDOCENV) $(SPHINXAPIDOC) $(SPHINXAPIDOCOPTS) -o $(SOURCEDIR)/api/ $(EVDIR) $(SPHINXAPIDOCEXCLUDE) @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) SPHINX_APIDOC_OPTIONS=$(SPHINXAPIDOCENV) $(SPHINXAPIDOC) $(SPHINXAPIDOCOPTS) -o $(SOURCEDIR)/api/ $(EVDIR) $(SPHINXAPIDOCEXCLUDE)
make _reformat_apidoc_headers make _reformat_apidoc_headers
git diff-index --quiet HEAD || git commit -a -m "Updated API autodoc index." -git diff-index --quiet HEAD || git commit -a -m "Updated API autodoc index."
_html-build: _html-build:
@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"

View file

@ -43,24 +43,25 @@ URL_REMAPS = {
"issues": "github:issue", "issues": "github:issue",
"bug": "github:issue", "bug": "github:issue",
"bug-report": "github:issue", "bug-report": "github:issue",
"Components/Components-Overview": "Components-Overview", "./Default-Command-Help": "api:evennia.commands.default#modules",
"Components-Overview": "Components-Overview", "../Components/Default-Command-Help": "api:evennia.commands.default#modules",
"Concepts/Concepts-Overview": "Concepts-Overview", "../../../Components/Default-Command-Help": "api:evennia.commands.default#modules",
"Concepts-Overview": "Concepts-Overview",
} }
_USED_REFS = {} _USED_REFS = {}
_CURRFILE = None _CURRFILE = None
def create_toctree(): def auto_link_remapper():
""" """
Create source/toc.md file - Auto-Remaps links to fit with the actual document file structure. Requires
all doc files to have a unique name.
- Creates source/toc.md file
""" """
global _CURRFILE global _CURRFILE
print(" -- Auto-Remapper") print(" -- Auto-Remapper starting.")
def _get_rel_source_ref(path): def _get_rel_source_ref(path):
"""Get the path relative the source/ dir""" """Get the path relative the source/ dir"""
@ -135,12 +136,14 @@ def create_toctree():
fname = part[0] if part else fname fname = part[0] if part else fname
fname = fname.rsplit(".", 1)[0] fname = fname.rsplit(".", 1)[0]
fname, *anchor = fname.rsplit("#", 1) fname, *anchor = fname.rsplit("#", 1)
_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]: if _CURRFILE in docref_map and fname in docref_map[_CURRFILE]:
cfilename = _CURRFILE.rsplit("/", 1)[-1] cfilename = _CURRFILE.rsplit("/", 1)[-1]
urlout = docref_map[_CURRFILE][fname] + ('#' + anchor[0] if anchor else '') urlout = docref_map[_CURRFILE][fname] + ('#' + anchor[0] if anchor else '')
if urlout != url and not _CURRFILE.endswith("toc.md"): if urlout != url:
print(f" {cfilename}: [{txt}]({url}) -> [{txt}]({urlout})") print(f" {cfilename}: [{txt}]({url}) -> [{txt}]({urlout})")
else: else:
urlout = url urlout = url
@ -166,12 +169,14 @@ def create_toctree():
fname = part[0] if part else fname fname = part[0] if part else fname
fname = fname.rsplit(".", 1)[0] fname = fname.rsplit(".", 1)[0]
fname, *anchor = fname.rsplit("#", 1) fname, *anchor = fname.rsplit("#", 1)
_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]: if _CURRFILE in docref_map and fname in docref_map[_CURRFILE]:
cfilename = _CURRFILE.rsplit("/", 1)[-1] cfilename = _CURRFILE.rsplit("/", 1)[-1]
urlout = docref_map[_CURRFILE][fname] + ('#' + anchor[0] if anchor else '') urlout = docref_map[_CURRFILE][fname] + ('#' + anchor[0] if anchor else '')
if urlout != url and not _CURRFILE.endswith("toc.md"): if urlout != url:
print(f" {cfilename}: [{txt}]: {url} -> [{txt}]: {urlout}") print(f" {cfilename}: [{txt}]: {url} -> [{txt}]: {urlout}")
else: else:
urlout = url urlout = url
@ -198,6 +203,10 @@ def create_toctree():
if count > 0: if count > 0:
print(f" -- Auto-corrected links in {count} documents.") 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:
print(f" ORPHANED DOC: no refs found to {src_url}.md")
# write tocfile # write tocfile
with open(_TOC_FILE, "w") as fil: with open(_TOC_FILE, "w") as fil:
fil.write("# Toc\n") fil.write("# Toc\n")
@ -212,15 +221,16 @@ def create_toctree():
if "Part1/" in ref: if "Part1/" in ref:
continue continue
if not "/" in ref:
ref = "./" + ref
linkname = ref.replace("-", " ") linkname = ref.replace("-", " ")
fil.write(f"\n- [{linkname}]({ref})") fil.write(f"\n- [{linkname}]({ref})")
# we add a self-reference so the toc itself is also a part of a toctree # 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```toctree::\n :hidden:\n\n toc\n```")
for (fname, src_url) in sorted(toc_map.items(), key=lambda tup: tup[0]): print(" -- Auto-Remapper finished.")
if fname not in _USED_REFS:
print(f" WARNING: no links found to {fname}.md ({src_url})")
if __name__ == "__main__": if __name__ == "__main__":
create_toctree() auto_link_remapper()

View file

@ -18,8 +18,10 @@ to you, but some things may still be useful.
## Coding away ## Coding away
- [Coding Introduction](./Coding-Introduction)
- [Ways to Debug](./Debugging) - [Ways to Debug](./Debugging)
- [Adding unit-tests](./Unit-Testing) - [Adding unit-tests](./Unit-Testing)
- [Things to remember when importing from evennia](./Flat-API)
## Advanced concepts ## Advanced concepts

View file

@ -1,47 +1,7 @@
# Evennia API # Things to remember about the flat API
Evennia makes much of its programming tools available directly from the top-level `evennia` package.
This is often referred to as Evennia's "flat" [Application Programming
Interface](https://en.wikipedia.org/wiki/Application_programming_interface) (API). The flat API
tries to collect and bring the most commonly used resources to the front in a way where everything
is available at a glance (in a flat display), making it a good place to start to learn Evennia.
> Evennia's flat (and full) API can be perused through the auto-generated [API Library
refence](github:evennia).
A good, interactive way to explore the flat API is to use [IPython](http://ipython.org/), a more
flexible version of the default Python shell. Inside your virtual environment you can install
IPython simply by
pip install ipython
Windows users should also install [PyReadline](http://ipython.org/pyreadline.html):
pip install pyreadline
With IPython installed, go to your game directory and run
evennia shell
This should give you the IPython shell automatically. Inside IPython
you then do
import evennia
Followed by
evennia.<TAB>
That is, write `evennia.` and press the TAB key. What pops up is the contents of the `evennia` top-
level package - in other words [the "flat" API](github:evennia#the-flat-api).
evennia.DefaultObject?
Starting to write the name of an API entity and pressing `<TAB>` will auto-complete the name. Adding
a question mark (`?`) to its name will show you its documentation. Append `??` to get the actual
source code. This way you can quickly explore Evennia and see what is available.
The flat API is a series of 'shortcuts' on the `evennia` main library root (defined in
`evennia/__init__.py`). Its componentas are documented [as part of the auto-documentation](../Evennia-API).
## To remember when importing from `evennia` ## To remember when importing from `evennia`

View file

@ -0,0 +1,9 @@
# Command System
- [Commands](./Commands)
- [Command Sets](./Command-Sets)
- [Command Auto-help](./Help-System#command-auto-help-system)
See also:
- [Default Command Help](api:evennia.commands.default#modules)
- [Adding Command Tutorial](../Howto/Starting/Part1/Adding-Commands)

View file

@ -8,7 +8,7 @@ The basic way for users to communicate with the game is through *Commands*. Thes
directly related to the game world such as *look*, *get*, *drop* and so on, or administrative directly related to the game world such as *look*, *get*, *drop* and so on, or administrative
commands such as *examine* or *@dig*. 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](api:evennia.commands.default#modules) 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 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 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 - can find the default commands in `evennia/commands/default`. You should not edit these directly -

View file

@ -20,10 +20,11 @@ than, the doc-strings of each component in the [API](../Evennia-API).
## Commands ## Commands
- [Commands](./Commands) - [Command system](./Command-System)
- [Command-Sets](./Command-Sets) - [Commands](./Commands)
- [The Connection Screen](./Connection-Screen) - [Command-Sets](./Command-Sets)
- [Available default Commands](./Default-Command-Help) - [The Connection Screen](./Connection-Screen)
- [Available default Commands](api:evennia.commands.default#modules)
- [Batch-Processors](./Batch-Processors) - [Batch-Processors](./Batch-Processors)
- [Batch-Code-Processor](./Batch-Code-Processor) - [Batch-Code-Processor](./Batch-Code-Processor)
- [Batch-Command-Processor](./Batch-Command-Processor) - [Batch-Command-Processor](./Batch-Command-Processor)

File diff suppressed because it is too large Load diff

View file

@ -1,9 +0,0 @@
# Command System
- [Commands](../Components/Commands)
- [Command Sets](../Components/Command-Sets)
- [Command Auto-help](../Components/Help-System#command-auto-help-system)
See also:
- [Default Command Help](../Components/Default-Command-Help)
- [Adding Command Tutorial](../Howto/Starting/Part1/Adding-Commands)

View file

@ -10,6 +10,7 @@ This documentation cover more over-arching concepts of Evennia, often involving
## Access ## Access
- [Multisession modes](./Multisession-modes)
- [Permissions](./Building-Permissions) - [Permissions](./Building-Permissions)
- [Banning](./Banning) - [Banning](./Banning)

View file

@ -83,7 +83,7 @@ planning at this stage can solve many problems before they happen.
In this section we will try to create an actual "map" object that an account can pick up and look In this section we will try to create an actual "map" object that an account can pick up and look
at. at.
Evennia offers a range of [default commands](../Components/Default-Command-Help) for Evennia offers a range of [default commands](api:evennia.commands.default#modules) for
[creating objects and rooms in-game](../Howto/Starting/Part1/Building-Quickstart). While readily accessible, these commands are made to do very [creating objects and rooms in-game](../Howto/Starting/Part1/Building-Quickstart). While readily accessible, these commands are made to do very
specific, restricted things and will thus not offer as much flexibility to experiment (for an specific, restricted things and will thus not offer as much flexibility to experiment (for an
advanced exception see [in-line functions](../Concepts/TextTags#new-inlinefuncs)). Additionally, entering long advanced exception see [in-line functions](../Concepts/TextTags#new-inlinefuncs)). Additionally, entering long

View file

@ -100,6 +100,8 @@ in mind for your own game, this will give you a good start.
- [View Character on website](./Web-Character-View-Tutorial) - [View Character on website](./Web-Character-View-Tutorial)
## Deep-dives ## Deep-dives
- [Parsing command inputs](./Parsing-commands-tutorial)
- [Understanding color-tags](./Understanding-Color-Tags) - [Understanding color-tags](./Understanding-Color-Tags)
- [Play paper&pen RPGs online with Evennia](./Evennia-for-roleplaying-sessions) - [Play paper&pen RPGs online with Evennia](./Evennia-for-roleplaying-sessions)
- [Evennia for Diku Users](./Evennia-for-Diku-Users) - [Evennia for Diku Users](./Evennia-for-Diku-Users)

View file

@ -3,7 +3,7 @@
[prev lesson](../Starting-Part1) | [next lesson](./Tutorial-World-Introduction) [prev lesson](../Starting-Part1) | [next lesson](./Tutorial-World-Introduction)
In this lesson we will test out what we can do in-game out-of-the-box. Evennia ships with In this lesson we will test out what we can do in-game out-of-the-box. Evennia ships with
[around 90 default commands](../../../Components/Default-Command-Help), and while you can override those as you please, [around 90 default commands](api:evennia.commands.default#modules), and while you can override those as you please,
they can be quite useful. they can be quite useful.
Connect and log into your new game and you will end up in the "Limbo" location. This Connect and log into your new game and you will end up in the "Limbo" location. This

View file

@ -56,7 +56,7 @@ This the the structure of the Evennia library:
- [`settings_default.py`](../../../Components/Server-Conf#Settings-file) - Root settings of Evennia. Copy settings - [`settings_default.py`](../../../Components/Server-Conf#Settings-file) - Root settings of Evennia. Copy settings
from here to `mygame/server/settings.py` file. from here to `mygame/server/settings.py` file.
- [`commands/`](../../../Components/Commands) - The command parser and handler. - [`commands/`](../../../Components/Commands) - The command parser and handler.
- `default/` - The [default commands](../../../Components/Default-Command-Help) and cmdsets. - `default/` - The [default commands](api:evennia.commands.default#modules) and cmdsets.
- [`comms/`](../../../Components/Communications) - Systems for communicating in-game. - [`comms/`](../../../Components/Communications) - Systems for communicating in-game.
- `contrib/` - Optional plugins too game-specific for core Evennia. - `contrib/` - Optional plugins too game-specific for core Evennia.
- `game_template/` - Copied to become the "game directory" when using `evennia --init`. - `game_template/` - Copied to become the "game directory" when using `evennia --init`.

View file

@ -314,9 +314,9 @@ def setup(app):
# build toctree file # build toctree file
sys.path.insert(1, os.path.join(os.path.dirname(os.path.dirname(__file__)), "docs")) sys.path.insert(1, os.path.join(os.path.dirname(os.path.dirname(__file__)), "docs"))
from docs.pylib import create_toctree from docs.pylib import auto_link_remapper
create_toctree.create_toctree() auto_link_remapper.auto_link_remapper()
print("Updated source/toc.md file") print("Updated source/toc.md file")
# custom lunr-based search # custom lunr-based search

View file

@ -21,11 +21,11 @@
- [Components/Channels](Components/Channels) - [Components/Channels](Components/Channels)
- [Components/Coding Utils](Components/Coding-Utils) - [Components/Coding Utils](Components/Coding-Utils)
- [Components/Command Sets](Components/Command-Sets) - [Components/Command Sets](Components/Command-Sets)
- [Components/Command System](Components/Command-System)
- [Components/Commands](Components/Commands) - [Components/Commands](Components/Commands)
- [Components/Communications](Components/Communications) - [Components/Communications](Components/Communications)
- [Components/Components Overview](Components/Components-Overview) - [Components/Components Overview](Components/Components-Overview)
- [Components/Connection Screen](Components/Connection-Screen) - [Components/Connection Screen](Components/Connection-Screen)
- [Components/Default Command Help](Components/Default-Command-Help)
- [Components/EvEditor](Components/EvEditor) - [Components/EvEditor](Components/EvEditor)
- [Components/EvMenu](Components/EvMenu) - [Components/EvMenu](Components/EvMenu)
- [Components/EvMore](Components/EvMore) - [Components/EvMore](Components/EvMore)
@ -52,7 +52,6 @@
- [Concepts/Banning](Concepts/Banning) - [Concepts/Banning](Concepts/Banning)
- [Concepts/Bootstrap & Evennia](Concepts/Bootstrap-&-Evennia) - [Concepts/Bootstrap & Evennia](Concepts/Bootstrap-&-Evennia)
- [Concepts/Building Permissions](Concepts/Building-Permissions) - [Concepts/Building Permissions](Concepts/Building-Permissions)
- [Concepts/Command System](Concepts/Command-System)
- [Concepts/Concepts Overview](Concepts/Concepts-Overview) - [Concepts/Concepts Overview](Concepts/Concepts-Overview)
- [Concepts/Custom Protocols](Concepts/Custom-Protocols) - [Concepts/Custom Protocols](Concepts/Custom-Protocols)
- [Concepts/Guest Logins](Concepts/Guest-Logins) - [Concepts/Guest Logins](Concepts/Guest-Logins)
@ -67,19 +66,19 @@
- [Concepts/Using MUX as a Standard](Concepts/Using-MUX-as-a-Standard) - [Concepts/Using MUX as a Standard](Concepts/Using-MUX-as-a-Standard)
- [Concepts/Web Features](Concepts/Web-Features) - [Concepts/Web Features](Concepts/Web-Features)
- [Concepts/Zones](Concepts/Zones) - [Concepts/Zones](Concepts/Zones)
- [Contrib/A voice operated elevator using events](Contribs/A-voice-operated-elevator-using-events) - [Contribs/A voice operated elevator using events](Contribs/A-voice-operated-elevator-using-events)
- [Contrib/Arxcode installing help](Contribs/Arxcode-installing-help) - [Contribs/Arxcode installing help](Contribs/Arxcode-installing-help)
- [Contrib/Building menus](Contribs/Building-menus) - [Contribs/Building menus](Contribs/Building-menus)
- [Contrib/Contrib Overview](Contribs/Contrib-Overview) - [Contribs/Contrib Overview](Contribs/Contrib-Overview)
- [Contrib/Dialogues in events](Contribs/Dialogues-in-events) - [Contribs/Dialogues in events](Contribs/Dialogues-in-events)
- [Contrib/Dynamic In Game Map](Contribs/Dynamic-In-Game-Map) - [Contribs/Dynamic In Game Map](Contribs/Dynamic-In-Game-Map)
- [Contrib/Static In Game Map](Contribs/Static-In-Game-Map) - [Contribs/Static In Game Map](Contribs/Static-In-Game-Map)
- [Contributing](Contributing) - [./Contributing](./Contributing)
- [Contributing Docs](Contributing-Docs) - [./Contributing Docs](./Contributing-Docs)
- [Evennia API](Evennia-API) - [./Evennia API](./Evennia-API)
- [Evennia Introduction](Evennia-Introduction) - [./Evennia Introduction](./Evennia-Introduction)
- [Glossary](Glossary) - [./Glossary](./Glossary)
- [How To Get And Give Help](How-To-Get-And-Give-Help) - [./How To Get And Give Help](./How-To-Get-And-Give-Help)
- [Howto/Add a wiki on your website](Howto/Add-a-wiki-on-your-website) - [Howto/Add a wiki on your website](Howto/Add-a-wiki-on-your-website)
- [Howto/Building a mech tutorial](Howto/Building-a-mech-tutorial) - [Howto/Building a mech tutorial](Howto/Building-a-mech-tutorial)
- [Howto/Coding FAQ](Howto/Coding-FAQ) - [Howto/Coding FAQ](Howto/Coding-FAQ)
@ -98,7 +97,7 @@
- [Howto/Manually Configuring Color](Howto/Manually-Configuring-Color) - [Howto/Manually Configuring Color](Howto/Manually-Configuring-Color)
- [Howto/Mass and weight for objects](Howto/Mass-and-weight-for-objects) - [Howto/Mass and weight for objects](Howto/Mass-and-weight-for-objects)
- [Howto/NPC shop Tutorial](Howto/NPC-shop-Tutorial) - [Howto/NPC shop Tutorial](Howto/NPC-shop-Tutorial)
- [Howto/Parsing command arguments, theory and best practices](Howto/Parsing-command-arguments,-theory-and-best-practices) - [Howto/Parsing commands tutorial](Howto/Parsing-commands-tutorial)
- [Howto/Starting/Part2/Game Planning](Howto/Starting/Part2/Game-Planning) - [Howto/Starting/Part2/Game Planning](Howto/Starting/Part2/Game-Planning)
- [Howto/Starting/Part2/Some Useful Contribs](Howto/Starting/Part2/Some-Useful-Contribs) - [Howto/Starting/Part2/Some Useful Contribs](Howto/Starting/Part2/Some-Useful-Contribs)
- [Howto/Starting/Part3/Implementing a game rule system](Howto/Starting/Part3/Implementing-a-game-rule-system) - [Howto/Starting/Part3/Implementing a game rule system](Howto/Starting/Part3/Implementing-a-game-rule-system)
@ -119,8 +118,8 @@
- [Howto/Weather Tutorial](Howto/Weather-Tutorial) - [Howto/Weather Tutorial](Howto/Weather-Tutorial)
- [Howto/Web Character Generation](Howto/Web-Character-Generation) - [Howto/Web Character Generation](Howto/Web-Character-Generation)
- [Howto/Web Character View Tutorial](Howto/Web-Character-View-Tutorial) - [Howto/Web Character View Tutorial](Howto/Web-Character-View-Tutorial)
- [Licensing](Licensing) - [./Licensing](./Licensing)
- [Links](Links) - [./Links](./Links)
- [Setup/Apache Config](Setup/Apache-Config) - [Setup/Apache Config](Setup/Apache-Config)
- [Setup/Choosing An SQL Server](Setup/Choosing-An-SQL-Server) - [Setup/Choosing An SQL Server](Setup/Choosing-An-SQL-Server)
- [Setup/Client Support Grid](Setup/Client-Support-Grid) - [Setup/Client Support Grid](Setup/Client-Support-Grid)
@ -139,8 +138,8 @@
- [Setup/Setup Overview](Setup/Setup-Overview) - [Setup/Setup Overview](Setup/Setup-Overview)
- [Setup/Setup Quickstart](Setup/Setup-Quickstart) - [Setup/Setup Quickstart](Setup/Setup-Quickstart)
- [Setup/Start Stop Reload](Setup/Start-Stop-Reload) - [Setup/Start Stop Reload](Setup/Start-Stop-Reload)
- [Unimplemented](Unimplemented) - [./Unimplemented](./Unimplemented)
- [index](index) - [./index](./index)
```toctree:: ```toctree::
:hidden: :hidden: