Long help text is broken into navigable pages

rocketbot/cogs/helpcog.py

@@ -2,8 +2,9 @@
 import re
 from typing import Union, Optional
 
-from discord import Interaction, Permissions, AppCommandType
+from discord import Interaction, Permissions, AppCommandType, ButtonStyle, InteractionResponse
 from discord.app_commands import Group, Command, autocomplete, guild_only, command, Choice
+from discord.ui import ActionRow, Button, LayoutView, TextDisplay
 
 from config import CONFIG
 from rocketbot.bot import Rocketbot
@@ -12,6 +13,9 @@ from rocketbot.utils import MOD_PERMISSIONS, dump_stacktrace
 
 HelpTopic = Union[Command, Group, BaseCog]
 
+# Potential place to break text neatly in large help content
+PAGE_BREAK = '\f'
+
 def choice_from_topic(topic: HelpTopic, include_full_command: bool = False) -> Choice:
 	if isinstance(topic, BaseCog):
 		return Choice(name=f'⚙ {topic.qualified_name}', value=f'cog:{topic.qualified_name}')
@@ -272,6 +276,7 @@ class HelpCog(BaseCog, name='Help'):
 				if isinstance(cmd, Group):
 					subcommand_count = len(cmd.commands)
 					text += f' ({subcommand_count} subcommands)'
+			text += PAGE_BREAK
 
 		if len(all_cog_tuples) > 0:
 			text += '\n### Module Configuration'
@@ -284,10 +289,9 @@ class HelpCog(BaseCog, name='Help'):
 					if setting.name == 'enabled':
 						continue
 					text += f'\n   - `/get` or `/set {cog.config_prefix}_{setting.name}`'
-		await interaction.response.send_message(
-			text,
-			ephemeral=True,
-		)
+				text += PAGE_BREAK
+
+		await self.__send_paged_help(interaction, text)
 
 	async def __send_keyword_help(self, interaction: Interaction, matching_topics: Optional[list[HelpTopic]]) -> None:
 		matching_commands = [
@@ -324,10 +328,8 @@ class HelpCog(BaseCog, name='Help'):
 			text += '\n### Modules'
 			for cog in matching_cogs:
 				text += f'\n- {cog.qualified_name}'
-		await interaction.response.send_message(
-			text,
-			ephemeral=True,
-		)
+
+		await self.__send_paged_help(interaction, text)
 
 	async def __send_command_help(self, interaction: Interaction, command_or_group: Union[Command, Group], addendum: Optional[str] = None) -> None:
 		text = ''
@@ -371,7 +373,8 @@ class HelpCog(BaseCog, name='Help'):
 					text += f'\n- `{param.name}`: {param.description}'
 					if not param.required:
 						text += ' (optional)'
-		await interaction.response.send_message(text, ephemeral=True)
+
+		await self.__send_paged_help(interaction, text)
 
 	async def __send_cog_help(self, interaction: Interaction, cog: BaseCog) -> None:
 		text = f'## :information_source: Module Help'
@@ -405,10 +408,92 @@ class HelpCog(BaseCog, name='Help'):
 				if setting.name == 'enabled':
 					continue
 				text += f'\n- `/get` or `/set {cog.config_prefix}_{setting.name}` - {setting.brief}'
-		await interaction.response.send_message(
-			text,
-			ephemeral=True,
-		)
+
+		await self.__send_paged_help(interaction, text)
+
+	async def __send_paged_help(self, interaction: Interaction, text: str) -> None:
+		pages = _paginate(text)
+		if len(pages) == 1:
+			await interaction.response.send_message(pages[0], ephemeral=True)
+		else:
+			await _update_paged_help(interaction, None, 0, pages)
+
+def _paginate(text: str) -> list[str]:
+	max_page_size = 2000
+	chunks = text.split(PAGE_BREAK)
+	pages = [ '' ]
+	for chunk in chunks:
+		if len(chunk) > max_page_size:
+			raise ValueError('Help content needs more page breaks! One chunk is too big for message.')
+		if len(pages[-1] + chunk) < max_page_size:
+			pages[-1] += chunk
+		else:
+			pages.append(chunk)
+	page_count = len(pages)
+	if page_count == 1:
+		return pages
+
+	# Do another pass and try to even out the page lengths
+	indices = [ i * len(chunks) // page_count for i in range(page_count + 1) ]
+	even_pages = [
+		''.join(chunks[indices[i]:indices[i + 1]])
+		for i in range(page_count)
+	]
+	for page in even_pages:
+		if len(page) > max_page_size:
+			# We made a page too big. Give up.
+			return pages
+	return even_pages
+
+async def _update_paged_help(interaction: Interaction, original_interaction: Optional[Interaction], current_page: int, pages: list[str]) -> None:
+	try:
+		view = _PagingLayoutView(current_page, pages, original_interaction or interaction)
+		resolved = interaction
+		if original_interaction is not None:
+			# We have an original interaction from the initial command and a
+			# new one from the button press. Use the original to swap in the
+			# new page in place, then acknowledge the new one to satisfy the
+			# API that we didn't fail.
+			await original_interaction.edit_original_response(
+				view=view,
+			)
+			if interaction is not original_interaction:
+				await interaction.response.defer(ephemeral=True, thinking=False)
+		else:
+			# Initial send
+			await resolved.response.send_message(
+				view=view,
+				ephemeral=True,
+				delete_message_after=60,
+			)
+	except BaseException as e:
+		dump_stacktrace(e)
+
+class _PagingLayoutView(LayoutView):
+	def __init__(self, current_page: int, pages: list[str], original_interaction: Optional[Interaction]):
+		super().__init__()
+		self.current_page: int = current_page
+		self.pages: list[str] = pages
+		self.text.content = self.pages[self.current_page]
+		self.original_interaction = original_interaction
+		if current_page <= 0:
+			self.handle_prev_button.disabled = True
+		if current_page >= len(self.pages) - 1:
+			self.handle_next_button.disabled = True
+
+	text = TextDisplay('')
+
+	row = ActionRow()
+
+	@row.button(label='< Prev')
+	async def handle_prev_button(self, interaction: Interaction, button: Button) -> None:
+		new_page = max(0, self.current_page - 1)
+		await _update_paged_help(interaction, self.original_interaction, new_page, self.pages)
+
+	@row.button(label='Next >')
+	async def handle_next_button(self, interaction: Interaction, button: Button) -> None:
+		new_page = min(len(self.pages) - 1, self.current_page + 1)
+		await _update_paged_help(interaction, self.original_interaction, new_page, self.pages)
 
 # Exclusions from keyword indexing
 trivial_words = {