From f8eed06a9c1a700c0456da2aff7eed44cc49a5e8 Mon Sep 17 00:00:00 2001 From: Redbot <4406896+Redbot@users.noreply.github.com> Date: Tue, 7 Oct 2025 21:14:02 -0500 Subject: [PATCH] add external docs for community plugins --- .github/workflows/mkdocs_deploy.yml | 2 + .gitignore | 10 +++++ community_docs.json | 42 +++++++++++++++++++++ hooks/mkdocs_hooks.py | 35 +++++++++++++++++ mkdocs.yml | 58 ++++++++++++++++++++++++++++- update_community_docs.py | 38 +++++++++++++++++++ 6 files changed, 183 insertions(+), 2 deletions(-) create mode 100644 community_docs.json create mode 100644 hooks/mkdocs_hooks.py create mode 100644 update_community_docs.py diff --git a/.github/workflows/mkdocs_deploy.yml b/.github/workflows/mkdocs_deploy.yml index 2ed5ed21e..da01c9240 100644 --- a/.github/workflows/mkdocs_deploy.yml +++ b/.github/workflows/mkdocs_deploy.yml @@ -29,5 +29,7 @@ jobs: 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: Update community plugin docs + run: python update_community_docs.py - name: Publish docs run: mkdocs gh-deploy diff --git a/.gitignore b/.gitignore index bc5bf60d2..2bc2ca077 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,13 @@ site/ .vscode/ .venv __pycache__/ + +# external docs +plugins/community-plugins/mq2camera/ +plugins/community-plugins/mq2dannet/ +plugins/community-plugins/mq2discord/ +plugins/community-plugins/mq2easyfind/ +plugins/community-plugins/mq2lootmanager/ +plugins/community-plugins/mq2nav/ +plugins/community-plugins/mq2sqlite/ +plugins/community-plugins/mqtexttospeech/ \ No newline at end of file diff --git a/community_docs.json b/community_docs.json new file mode 100644 index 000000000..36eaf9288 --- /dev/null +++ b/community_docs.json @@ -0,0 +1,42 @@ +{ + "plugins/community-plugins/mq2discord": { + "url": "https://gitlab.com/Redbot/mq2discord.git", + "branch": "docs-dir", + "docs_path": "docs" + }, + "plugins/community-plugins/mq2sqlite": { + "url": "https://gitlab.com/Redbot/mq2sqlite.git", + "branch": "docs-dir", + "docs_path": "docs" + }, + "plugins/community-plugins/mq2camera": { + "url": "https://github.com/Redbot/MQ2Camera.git", + "branch": "docs-dir", + "docs_path": "docs" + }, + "plugins/community-plugins/mq2dannet": { + "url": "https://github.com/Redbot/MQ2Dan.git", + "branch": "docs-dir", + "docs_path": "MQ2DanNet/docs" + }, + "plugins/community-plugins/mq2easyfind": { + "url": "https://github.com/Redbot/MQ2EasyFind.git", + "branch": "docs-dir", + "docs_path": "docs" + }, + "plugins/community-plugins/mq2lootmanager": { + "url": "https://github.com/Redbot/MQ2LootManager.git", + "branch": "docs-dir", + "docs_path": "docs" + }, + "plugins/community-plugins/mq2nav": { + "url": "https://github.com/Redbot/MQ2Nav.git", + "branch": "doc", + "docs_path": "doc" + }, + "plugins/community-plugins/mqtexttospeech": { + "url": "https://github.com/Redbot/MQTextToSpeech.git", + "branch": "docs-dir", + "docs_path": "docs" + } +} diff --git a/hooks/mkdocs_hooks.py b/hooks/mkdocs_hooks.py new file mode 100644 index 000000000..c78ba0f6d --- /dev/null +++ b/hooks/mkdocs_hooks.py @@ -0,0 +1,35 @@ +import mkdocs.plugins + +@mkdocs.plugins.event_priority(0) #default priority +def on_page_context(context, page, config, nav): + """ + Constructs edit URLs using page frontmatter, usually added in .meta.yml files. + """ + # Use the documentation repository for edit URLs + docs_repo_url = page.meta.get("docs_repository") or config.repo_url + + # Use the documentation edit URI + edit_uri = page.meta.get("docs_edit_uri") or config.edit_uri + + # Determine the file path for the edit URL + if "docs_file_path" in page.meta: + # Complete override of file path + file_src_uri = page.meta["docs_file_path"] + else: + # Use original path with optional transformations + file_src_uri = page.file.src_uri + + # Apply path transformation if specified + if "docs_path_transform" in page.meta: + transform = page.meta["docs_path_transform"] + if isinstance(transform, dict) and "from" in transform and "to" in transform: + from_path = transform["from"] + to_path = transform["to"] + if file_src_uri.startswith(from_path): + file_src_uri = to_path + file_src_uri[len(from_path):] + + # Only build edit_url if we have the required components + if docs_repo_url and edit_uri: + page.edit_url = f"{docs_repo_url.rstrip('/')}/{edit_uri}{file_src_uri}" + + return context \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index e8af9cbc7..fc09b1f29 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,7 @@ site_author: Macroquest Developers # Repository repo_name: MacroQuest repo_url: https://github.com/macroquest/macroquest -edit_uri: https://github.com/macroquest/docs/edit/master +edit_uri: ../docs/edit/master docs_dir: . # Copyright @@ -15,6 +15,8 @@ copyright: Copyright © 2002-2022 Macroquest Developers extra_css: - stylesheets/extra.css +hooks: + - hooks/mkdocs_hooks.py # Navigation nav: @@ -151,14 +153,48 @@ nav: - MQ2AutoSkills: plugins/community-plugins/mq2autoskills.md - MQ2Bandolier: plugins/community-plugins/mq2bandolier.md - MQ2BuffTool: plugins/community-plugins/mq2bufftool.md + - MQ2Camera: + - plugins/community-plugins/mq2camera/index.md + - /camera: plugins/community-plugins/mq2camera/cmd-camera.md - MQ2Cast: plugins/community-plugins/mq2cast.md - MQ2ChatEvents: plugins/community-plugins/mq2chatevents.md - MQ2Cursor: plugins/community-plugins/mq2cursor.md + - MQ2DanNet: + - plugins/community-plugins/mq2dannet/index.md + - /djoin: plugins/community-plugins/mq2dannet/cmd-djoin.md + - /dleave: plugins/community-plugins/mq2dannet/cmd-dleave.md + - /dtell: plugins/community-plugins/mq2dannet/cmd-dtell.md + - /dgtell: plugins/community-plugins/mq2dannet/cmd-dgtell.md + - /dexecute: plugins/community-plugins/mq2dannet/cmd-dexecute.md + - /dgexecute: plugins/community-plugins/mq2dannet/cmd-dgexecute.md + - /dggexecute: plugins/community-plugins/mq2dannet/cmd-dggexecute.md + - /dgrexecute: plugins/community-plugins/mq2dannet/cmd-dgrexecute.md + - /dgzexecute: plugins/community-plugins/mq2dannet/cmd-dgzexecute.md + - /dgaexecute: plugins/community-plugins/mq2dannet/cmd-dgaexecute.md + - /dggaexecute: plugins/community-plugins/mq2dannet/cmd-dggaexecute.md + - /dgraexecute: plugins/community-plugins/mq2dannet/cmd-dgraexecute.md + - /dgzaexecute: plugins/community-plugins/mq2dannet/cmd-dgzaexecute.md + - /dnet: plugins/community-plugins/mq2dannet/cmd-dnet.md + - /dobserve: plugins/community-plugins/mq2dannet/cmd-dobserve.md + - /dquery: plugins/community-plugins/mq2dannet/cmd-dquery.md + - TLO:DanNet: plugins/community-plugins/mq2dannet/tlo-dannet.md + - DataType:DanNet: plugins/community-plugins/mq2dannet/datatype-dannet.md + - DataType:DanObservation: plugins/community-plugins/mq2dannet/datatype-danobservation.md - MQ2DPSAdv: plugins/community-plugins/mq2dpsadv.md - MQ2Debuffs: plugins/community-plugins/mq2debuffs.md + - MQ2Discord: + - plugins/community-plugins/mq2discord/index.md + - /discord: plugins/community-plugins/mq2discord/cmd-discord.md + - Create a Discord Bot Account: plugins/community-plugins/mq2discord/Create_Bot_Account.md - MQ2Cecho: plugins/community-plugins/mq2cecho.md - MQ2EQBC: plugins/community-plugins/mq2eqbc/README.md - MQ2EQBC:Revisions: plugins/community-plugins/mq2eqbc/mq2eqbc-revisions.md + - MQ2EasyFind: + - plugins/community-plugins/mq2easyfind/index.md + - /easyfind: plugins/community-plugins/mq2easyfind/cmd-easyfind.md + - /travelto: plugins/community-plugins/mq2easyfind/cmd-travelto.md + - TLO:EasyFind: plugins/community-plugins/mq2easyfind/tlo-easyfind.md + - DataType:EasyFind: plugins/community-plugins/mq2easyfind/datatype-easyfind.md - MQ2Events: plugins/community-plugins/mq2events.md - MQ2Exchange: plugins/community-plugins/mq2exchange.md - MQ2FakeLink: plugins/community-plugins/mq2fakelink.md @@ -166,6 +202,9 @@ nav: - MQ2GMCheck: plugins/community-plugins/mq2gmcheck.md - MQ2HUDMove: plugins/community-plugins/mq2hudmove.md - MQ2LinkDB: plugins/community-plugins/mq2linkdb.md + - MQ2LootManager: + - plugins/community-plugins/mq2lootmanager/index.md + - /lootmanager: plugins/community-plugins/mq2lootmanager/cmd-lootmanager.md - MQ2Medley: plugins/community-plugins/mq2medley.md - MQ2Melee: plugins/community-plugins/mq2melee.md - MQ2Missing: plugins/community-plugins/mq2missing.md @@ -174,6 +213,11 @@ nav: - MQ2MoveUtils:v11 Revisions: plugins/community-plugins/mq2moveutils/mq2moveutils-v11-revisions.md - MQ2MoveUtils:v11 FAQ: plugins/community-plugins/mq2moveutils/mq2moveutils-v11-faq.md - MQ2MoveUtils (old): plugins/community-plugins/mq2moveutils/mq2moveutils-old.md + - MQ2Nav: + - plugins/community-plugins/mq2nav/index.md + - /navigate: plugins/community-plugins/mq2nav/cmd-navigate.md + - TLO:Navigation: plugins/community-plugins/mq2nav/tlo-navigation.md + - DataType:Navigation: plugins/community-plugins/mq2nav/datatype-navigation.md - MQ2NetBots: plugins/community-plugins/mq2netbots.md - MQ2NetHeal: plugins/community-plugins/mq2netheal.md - MQ2PQ: plugins/community-plugins/mq2pq.md @@ -182,11 +226,21 @@ nav: - MQ2Sound: plugins/community-plugins/mq2sound.md - MQ2Spawn: plugins/community-plugins/mq2spawn.md - MQ2SpawnMaster: plugins/community-plugins/mq2spawnmaster.md + - MQ2SQLite: + - plugins/community-plugins/mq2sqlite/index.md + - /sqlite: plugins/community-plugins/mq2sqlite/cmd-sqlite.md + - TLO:Sqlite: plugins/community-plugins/mq2sqlite/tlo-sqlite.md + - DataType:Sqlite: plugins/community-plugins/mq2sqlite/datatype-sqlite.md - MQ2Targets: plugins/community-plugins/mq2targets.md - MQ2Timestamp: plugins/community-plugins/mq2timestamp.md - MQ2Tracking: plugins/community-plugins/mq2tracking.md - MQ2Twist: plugins/community-plugins/mq2twist/README.md - MQ2Twist:Revisions: plugins/community-plugins/mq2twist/mq2twist-revisions.md + - MQTextToSpeech: + - plugins/community-plugins/mqtexttospeech/index.md + - /tts: plugins/community-plugins/mqtexttospeech/cmd-tts.md + - TLO:TTS: plugins/community-plugins/mqtexttospeech/tlo-tts.md + - DataType:TTS: plugins/community-plugins/mqtexttospeech/datatype-tts.md - MQ2Vendors: plugins/community-plugins/mq2vendors.md - MQ2MQ2Web: plugins/community-plugins/mq2web.md - MQ2XPTracker: plugins/community-plugins/mq2xptracker.md @@ -668,6 +722,7 @@ plugins: - search - macros - include-markdown + - meta - same-dir - redirects: redirect_maps: @@ -696,7 +751,6 @@ markdown_extensions: - def_list - footnotes - mdx_math - - meta - toc: permalink: true - pymdownx.arithmatex: diff --git a/update_community_docs.py b/update_community_docs.py new file mode 100644 index 000000000..bd306dc82 --- /dev/null +++ b/update_community_docs.py @@ -0,0 +1,38 @@ +#!/usr/bin/env python3 +# Clone plugin repos, copy docs, delete clones +import subprocess +import json +import shutil +import tempfile +import os + +def update_plugin(prefix, url, branch, docs_path): + plugin_name = os.path.basename(prefix) + + with tempfile.TemporaryDirectory() as tmp: + print(f"Cloning {plugin_name}...") + subprocess.run(f'git clone -b {branch} --depth 1 {url} {tmp}/repo', + shell=True, check=True, capture_output=True) + + src = os.path.join(tmp, 'repo', docs_path) + if not os.path.exists(src): + print(f" Warning: {docs_path} not found, skipping") + return + + print(f" Copying {docs_path} -> {prefix}") + if os.path.exists(prefix): + shutil.rmtree(prefix) + shutil.copytree(src, prefix) + +def main(): + with open('community_docs.json', 'r') as f: + plugins = json.load(f) + + for prefix, config in plugins.items(): + update_plugin(prefix, config['url'], config['branch'], config['docs_path']) + + print("\nDone!") + +if __name__ == '__main__': + main() +