embedding commands and datatypes onto a page

.github/workflows/mkdocs_deploy.yml

@@ -23,16 +23,10 @@ jobs:
           fetch-depth: 0
       - name: Setup Python
         uses: actions/setup-python@v2
-      - name: Install mkdocs
+      - name: Install dependencies
         run:  |
           pip install --upgrade pip
-          pip install mkdocs mkdocs-gen-files
-          pip install mkdocs-material
-          pip install mkdocs-redirects
-          pip install mkdocs-same-dir
-          pip install python-markdown-math
-          pip install mkdocs-macros-plugin
-          pip install eq_lexers
+          pip install -r requirements.txt
       - name: Configure git as github-actions bot
         run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
       - name: Publish docs

README.md

@@ -8,14 +8,14 @@ Welcome to the MacroQuest Documentation.
 
 # About MacroQuest
 
-MacroQuest, also known as MQ, or most recently MQNext, is the next generation in development of the platform for the customization and automation of [EverQuest](http://www.everquest.com).  MacroQuest is, and has always been, open source software.
+MacroQuest, also known as MQ, is a platform for the customization and automation of [EverQuest](http://www.everquest.com).  MacroQuest is, and has always been, open source software.
 
-MacroQuest is as useful as you wish to make it. You can utilize it just for the capabilities of the map and other plugins, or you can further enhance EverQuest through the use of lua scripts, macros, or designing your own plugin.
+MacroQuest is as useful as you wish to make it. You can utilize it just for the capabilities of the [map](plugins/core-plugins/map/README.md) and other plugins, or you can further enhance EverQuest through the use of [lua scripts](lua/README.md), [macros](macros/README.md), or designing your own [plugin](plugins/README.md).
 
 However, there are some issues you need to understand:
 
-* First and foremost, the use of MacroQuest is a violation of the EULA of EverQuest.
-* This means that if you use MacroQuest, you risk your account being suspended for a period of time, or in extreme cases, having your account(s) permanently banned.
+* First and foremost, the use of MacroQuest is a violation of the EULA of EverQuest.  
+* This means that if you use MacroQuest, you risk your account being suspended for a period of time, or in extreme cases, having your account(s) permanently banned.  
 
 _If you are not prepared for such circumstances, stop here and do not continue._
 

macros/README.md

@@ -1,6 +1,6 @@
 # Macro Reference
 
-The use of macros is what really makes MacroQuest extremely powerful. Additional in-game functionality like [the map](../plugins/core-plugins/mq2map/), cross-zone targeting, enhanced [/who](../reference/commands/who.md), custom binds, [the HUD](../plugins/core-plugins/mq2hud/) and [plugins](../plugins/README.md) are useful, but macroing is what **Macro**Quest is all about.
+The use of macros is what really makes MacroQuest extremely powerful. Additional in-game functionality like [the map](../plugins/core-plugins/map/), cross-zone targeting, enhanced [/who](../reference/commands/who.md), custom binds, [the HUD](../plugins/core-plugins/hud/) and [plugins](../plugins/README.md) are useful, but macroing is what **Macro**Quest is all about.
 
 See [Getting Started](getting-started.md) for some introductory information about macros. This page is concerned primarily with all the relevant information required to create your own macros.
 

macros/beginners-guide-datatypes.md

@@ -10,7 +10,7 @@ In order to use these built-in variables, you need to pick a Top-Level Object to
 
 ### Example 1: Mana Percentage
 
-Say you want to display your current Mana Percentage in a [HUD](../plugins/core-plugins/mq2hud/README.md) or use it in a macro.
+Say you want to display your current Mana Percentage in a [HUD](../plugins/core-plugins/hud/README.md) or use it in a macro.
 
 * First off, you look through the [list of TLOs](../reference/top-level-objects/README.md) and pick one that best suits the information you're looking for. The [Me TLO](../reference/top-level-objects/tlo-me.md) looks like a good bet.
 * Opening that page, you see that the Me TLO has access to the [_character_](../reference/data-types/datatype-character.md) datatype and the [_spawn_](../reference/data-types/datatype-spawn.md) datatype. The _character_ datatype contains information about your own character, mostly things that only you will know (eg. how much mana you have, what spells you have loaded, etc). Since your character is also a spawn in the EQ world (ie. other people can see you and interact with you), you are also able to access the _spawn_ datatype, which gives information that other characters in the same zone may know (eg. your location, your race, your class, etc).

main.py

@@ -1,3 +1,6 @@
+import re
+from pathlib import Path, PurePosixPath
+
 def define_env(env):
 
     @env.macro
@@ -14,4 +17,90 @@ def renderMember(name, type=None, params=None, toc_label=None):
         if toc_label is None:
             toc_label = f'{name}{params_str}'
 
-        return f"{type_str} `{name}{params_str}` {{ #{toc_label} data-toc-label='{toc_label}' }}"
+        return f"{type_str} `{name}{params_str}` {{ #{toc_label} data-toc-label='{toc_label}' }}"
+
+    # output a read more link if the file has sections beyond Members/Forms/Description
+    @env.macro
+    def readMore(doc_file):
+        page = env.variables.page
+        file_result = read_file(doc_file, page)
+
+        if not file_result["success"]:
+            return ""
+
+        has_extra = has_extra_sections(file_result["content"])
+        doc_url = file_result["doc_url"]
+
+        if has_extra:
+            return f'[:material-book-arrow-right-outline:]({doc_url} "Full documentation")'
+        return ''
+
+# == Helper Functions ==
+
+def read_file(file_path, page):
+    try:
+        doc_path = Path(file_path)
+        content = doc_path.read_text()
+        base_dir = doc_path.parent
+        doc_url = relative_link(file_path, page.file.src_uri) # src_uri is the path to the embedding page
+        return {
+            "content": content,
+            "base_dir": base_dir,
+            "doc_url": doc_url,
+            "success": True,
+            "error": None
+        }
+    except Exception as e:
+        return {
+            "content": "",
+            "base_dir": None,
+            "doc_url": "#",
+            "success": False,
+            "error": str(e)
+        }
+
+# create an mkdocs-style url that's relative to the embedding page
+def relative_link(target_file_path, embedding_page_src_uri, base_dir=None):
+    # Absolute path of the target markdown file
+    target_path = (PurePosixPath(base_dir) / target_file_path if base_dir else PurePosixPath(target_file_path))
+    embedding_file = PurePosixPath(embedding_page_src_uri)
+
+    if embedding_file.stem.lower() in ("readme", "index"):
+        # main/guide/README.md   ->  main/guide/
+        output_dir = embedding_file.parent
+    else:
+        # main/foo.md       ->  main/foo/
+        output_dir = embedding_file.parent / embedding_file.stem
+
+    # Relative path from the embedding page to the target file
+    relative_path = target_path.relative_to(output_dir, walk_up=True)
+
+    # strip .md, add trailing slash
+    if relative_path.name.lower() in ("index.md", "readme.md"):
+        parent_dir = relative_path.parent
+        return "./" if str(parent_dir) == "." else f"{parent_dir}/"
+    return f"{relative_path.with_suffix('')}/"
+
+# extra sections beyond Members/Forms/Description
+def has_extra_sections(content):
+    SECTION_PATTERN = r'^##\s+(.+?)\s*$'
+    target_sections = {"Syntax", "Members", "Forms", "Description", "Associated DataTypes", "DataTypes", "See also"}
+
+    lines = content.split('\n')
+    in_datatypes_section = False
+
+    # Find all section headers that aren't within an include block
+    for i, line in enumerate(lines):
+        if '<!--tlo-datatypes-start-->' in line:
+            in_datatypes_section = True
+        elif '<!--tlo-datatypes-end-->' in line:
+            in_datatypes_section = False
+
+        if not in_datatypes_section:
+            match = re.match(SECTION_PATTERN, line)
+            if match:
+                section = match.group(1).strip()
+                if section not in target_sections:
+                    return True
+
+    return False

main/README.md

@@ -17,7 +17,7 @@ MacroQuest becomes part of EverQuest when you play, and anything you do inside o
 The following common EverQuest slash commands are enhanced by MacroQuest:
 
 * [/cast](../reference/commands/cast.md)
-* [/charinfo](../reference/commands/charinfo.md)
+* [/char](../reference/commands/char.md)
 * [/help](../reference/commands/help.md)
 * [/location](../reference/commands/location.md)
 * [/target](../reference/commands/mqtarget.md)
@@ -38,7 +38,7 @@ The following commonly used slash commands are added by MacroQuest:
 * [/itemtarget](../reference/commands/itemtarget.md)
 * [/macro](../reference/commands/macro.md)
 * [/memspell](../reference/commands/memspell.md)
-* [/mqfont](../plugins/core-plugins/mq2chatwnd/mqfont.md)
+* [/mqfont](../plugins/core-plugins/chatwnd/mqfont.md)
 * [/mqpause](../reference/commands/mqpause.md)
 * [/multiline](../reference/commands/multiline.md)
 * [/popup](../reference/commands/popup.md)
@@ -66,7 +66,7 @@ To end a macro, use this command:
 
 `/endmacro`
 
-See the [Getting Startaed](../macros/getting-started.md) section for further information on macros, and [/macro](../reference/commands/macro.md) and [/endmacro](../reference/commands/endmacro.md) for starting and stopping.
+See the [Getting Started](../macros/getting-started.md) section for further information on macros, and [/macro](../reference/commands/macro.md) and [/endmacro](../reference/commands/endmacro.md) for starting and stopping.
 
 ### Plugins
 
@@ -106,7 +106,7 @@ See the [Custom UIs](./features/custom-uis.md) page for further information on w
 
 ## HUDs
 
-MacroQuest can enable a custom Heads Up Display to show almost any kind of data on top of your UI. Instructions for configuration as well as further information can be found on the [MQ2HUD](../plugins/core-plugins/mq2hud/) page.
+MacroQuest can enable a custom Heads Up Display to show almost any kind of data on top of your UI. Instructions for configuration as well as further information can be found on the [HUD](../plugins/core-plugins/hud/) page.
 
 ## CFG Files
 
@@ -118,7 +118,7 @@ See the [CFG Files](./features/cfg-files.md) section for further information.
 
   Chat window.\*\*
 
-You need to load the [MQ2Map](../plugins/core-plugins/mq2map/) plugin using the command "/plugin MQ2Map" in-game.
+You need to load the [Map](../plugins/core-plugins/map/) plugin using the command "/plugin Map" in-game.
 
 * **When you execute /mapfilter with any options, all layers that were previously visible disappear.**
 

main/features/custom-uis.md

@@ -4,7 +4,7 @@
 
 MacroQuest has several built-in EQTypes that can be used to customize your UI. These EQTypes function the same as those in EQ, however allow you to display information in your UI that you normally would not be able to see. Alternatively, if there is no built-in EQType, you can use Tooltips to display custom MQ2 information (including data/variables from plugins).
 
-See the [MQ2Labels](../../plugins/core-plugins/mq2labels.md) page for the EQType definitions and examples.
+See the [Labels](../../plugins/core-plugins/labels/index.md) page for the EQType definitions and examples.
 
 ## List of Custom UIs
 

main/features/framelimiter.md

@@ -11,79 +11,65 @@ Frame lmiter settings can be modified in the MacroQuest Settings window.
 
 ## Commands
 
-`/framelimiter [COMMAND] {OPTIONS}`
-
-Frame limiter tool: allows adjusting internal frame limiter settings.
-
-```text
-enable -- turn the framelimiter on (background)
-on -- turn the framelimiter on (background)
-disable -- turn the rendering client off
-off -- turn the rendering client off
-toggle -- set/toggle the framelimiter functionality
-enablefg -- turn the framelimiter on (foreground)
-onfg -- turn the framelimiter on (foreground)
-disablefg -- turn the framelimiter off (foreground)
-offfg -- turn the framelimiter off (foreground)
-togglefg -- set/toggle the framelimiter (foreground)
-savebychar -- set/toggle saving settings by character
-bgrender -- set/toggle rendering when client is in background
-imguirender -- set/toggle rendering ImGui when rendering is otherwise disabled
-uirender -- set/toggle rendering the UI when rendering is otherwise disabled
-clearscreen -- set/toggle clearing (blanking) the screen when rendering is disabled
-bgfps -- set the FPS rate for the background process
-fgfps -- set the FPS rate for the foreground process
-simfps -- sets the minimum FPS the simulation will run
-reloadsettings -- reload settings from ini
--h, -?, help -- displays this help text
-```
+<a href="../../../reference/commands/framelimiter/">
+{% 
+  include-markdown "reference/commands/framelimiter.md" 
+  start="<!--cmd-syntax-start-->" 
+  end="<!--cmd-syntax-end-->" 
+%}
+</a>
+:    {% include-markdown "reference/commands/framelimiter.md" 
+        start="<!--cmd-desc-start-->" 
+        end="<!--cmd-desc-end-->" 
+        trailing-newlines=false 
+     %} {{ readMore('reference/commands/framelimiter.md') }}
+{% 
+  include-markdown "reference/commands/framelimiter.md" 
+  start="<!--cmd-options-start-->" 
+  end="<!--cmd-options-end-->" 
+%}
 
 ## Top-Level Objects
 
-### [FrameLimiter](reference\top-level-objects\tlo-framelimiter.md)
-
-## Members
-
-### {{ renderMember(type='float', name='BackgroundFPS') }}
-
-:   Value of the target background fps setting.
-
-### {{ renderMember(type='bool', name='ClearScreen') }}
-
-:   Value of the clear screen when not rendering setting.
-
-### {{ renderMember(type='float', name='CPU') }}
-
-:   Current CPU usage as %
-
-### {{ renderMember(type='bool', name='Enabled') }}
-
-:   TRUE if the frame limiter feature is currently active.
-
-### {{ renderMember(type='float', name='ForegroundFPS') }}
-
-:   Value of the target foreground fps setting.
-
-### {{ renderMember(type='float', name='MinSimulationFPS') }}
-
-:   Value of the minimum simualtion rate setting.
-
-### {{ renderMember(type='float', name='RenderFPS') }}
-
-:   Current graphics scene frame rate (visible fps).
-
-### {{ renderMember(type='bool', name='SaveByChar') }}
-
-:   TRUE if settings for the frame limiter are being saved by character.
-
-### {{ renderMember(type='float', name='SimulationFPS') }}
-
-:   Current simulation frame rate (game updates per second).
-
-### {{ renderMember(type='string', name='Status') }}
-
-:   Either "Foreground" or "Background".
-
-[bool]: datatype-bool.md
-[float]: datatype-float.md
-[string]: datatype-string.md
+## [FrameLimiter](../../reference/top-level-objects/tlo-framelimiter.md)
+{%
+  include-markdown "reference/top-level-objects/tlo-framelimiter.md"
+  start="<!--tlo-desc-start-->"
+  end="<!--tlo-desc-end-->"
+  trailing-newlines=false
+%} {{ readMore('reference/top-level-objects/tlo-framelimiter.md') }}
+
+<h2>Forms</h2>
+{%
+  include-markdown "reference/top-level-objects/tlo-framelimiter.md"
+  start="<!--tlo-forms-start-->"
+  end="<!--tlo-forms-end-->"
+  heading-offset=0
+%}
+{% 
+  include-markdown "reference/top-level-objects/tlo-framelimiter.md" 
+  start="<!--tlo-linkrefs-start-->"
+  end="<!--tlo-linkrefs-end-->"
+%}
+
+## Associated DataTypes
+
+## [framelimiter](../../reference/data-types/datatype-framelimiter.md)
+{%
+  include-markdown "reference/data-types/datatype-framelimiter.md"
+  start="<!--dt-desc-start-->"
+  end="<!--dt-desc-end-->"
+  trailing-newlines=false
+%} {{ readMore('reference/data-types/datatype-framelimiter.md') }}
+:    <h2>Members</h2>
+    {%
+    include-markdown "reference/data-types/datatype-framelimiter.md"
+    start="<!--dt-members-start-->"
+    end="<!--dt-members-end-->"
+    heading-offset=0
+    %}
+    {%
+    include-markdown "reference/data-types/datatype-framelimiter.md"
+    start="<!--dt-linkrefs-start-->"
+    end="<!--dt-linkrefs-end-->"
+    %}