docs.py

# minqlxtended - A Quake Live server administrator bot.
# Copyright (C) 2015 Mino <mino@minomino.org>
# Copyright (C) 2024 Thomas Jones <me@thomasjones.id.au>

# This file is part of minqlxtended.

# minqlxtended is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# minqlxtended is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with minqlxtended. If not, see <http://www.gnu.org/licenses/>.

import minqlxtended
import os.path
from os import linesep
from datetime import datetime
from html import escape

class docs(minqlxtended.Plugin):
    def __init__(self):
        super().__init__()
        self.add_command("gendocs", self.cmd_gendocs, permission=5, usage="[excluded_plugins]")

    def cmd_gendocs(self, players, msg, channel):
        """Generate a command list based on currently loaded plugins in HTML with Twig filtering."""
        if len(msg) > 1:
            excluded = [s.lower() for s in msg[1:]]
        else:
            excluded = []

        prefix = self.get_cvar("qlx_commandPrefix")
        cmds = {}
        for cmd in minqlxtended.COMMANDS.commands:
            if cmd.plugin.__class__.__name__ in excluded:  # Skip excluded plugins.
                continue

            if cmd.permission not in cmds:
                cmds[cmd.permission] = [cmd]
            else:
                cmds[cmd.permission].append(cmd)

        out = f"<p><small><em>Last updated:</em> {datetime.now().replace(microsecond=0)}</small></p>\n"
        for perm in sorted(cmds.keys()):
            if perm:
                out += f"{{% if permissionLevel >= {perm} %}}\n"

            out += f"<h3>Permission level <strong>{perm}</strong>:</h3>\n"
            out += "<ul>\n"
            for cmd in sorted(cmds[perm], key=lambda x: x.plugin.__class__.__name__):
                out += "  <li>\n"
                name = prefix + cmd.name[0] if cmd.prefix else cmd.name[0]
                out += f"    <code>{name}</code>"
                if len(cmd.name) > 1:  # Aliases?
                    out += " (alternatively "
                    for alias in cmd.name[1:]:
                        name_alias = prefix + alias if cmd.prefix else alias
                        out += f"<code>{name_alias}</code>, "
                    out = out[:-2] + ")"
                out += f" from plug-in <em>{cmd.plugin.__class__.__name__}</em>.\n"
                
                # Docstring.
                if cmd.handler.__doc__:
                    out += f'    <p class="font-monospace">{escape(cmd.handler.__doc__.strip()).replace(linesep, "<br>")}</p>\n'

                # Usage
                if cmd.usage:
                    out += f"    <p><em>Usage</em>: <code>{name} {escape(cmd.usage.strip())}</code></p>\n"

                out += "  </li>\n"
            out += "</ul>\n"

            if perm:
                out += "{% endif %}\n"
        
        out += f'<em>Automatically generated by <a href="https://github.com/tjone270/minqlxtended">minqlxtended {minqlxtended.__version__} (with plug-ins {minqlxtended.__plugins_version__}.)</a></em>'

        with open(os.path.join(self.get_cvar("fs_basepath"), "command_list.twig"), "w") as f:
            f.write(out)

        channel.reply("^7Command list generated!")