From 1e5dada0c8115f0692c022554b155db1feb086c7 Mon Sep 17 00:00:00 2001 From: Lemon Rose Date: Mon, 16 Oct 2023 13:06:12 +0530 Subject: [PATCH] tags doc init --- docs/Makefile | 20 +++++++ docs/conf.py | 70 ++++++++++++++++++++++ docs/credits.rst | 9 +++ docs/index.rst | 63 +++++++++++++++++++ docs/make.bat | 35 +++++++++++ docs/requirements.txt | 8 +++ docs/tags/blocks.rst | 74 +++++++++++++++++++++++ docs/tags/default_variables.rst | 100 +++++++++++++++++++++++++++++++ docs/tags/example_tags.rst | 54 +++++++++++++++++ docs/tags/owner_guide.rst | 92 ++++++++++++++++++++++++++++ docs/tags/tse_blocks.rst | 103 ++++++++++++++++++++++++++++++++ 11 files changed, 628 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/credits.rst create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/tags/blocks.rst create mode 100644 docs/tags/default_variables.rst create mode 100644 docs/tags/example_tags.rst create mode 100644 docs/tags/owner_guide.rst create mode 100644 docs/tags/tse_blocks.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..f89504c6 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,70 @@ +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = "Seina-Cogs" +copyright = "2021, PhenoM4n4n, inthedark.org" +author = "PhenoM4n4n, inthedark.org" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "recommonmark", + "sphinx_rtd_theme", + "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +intersphinx_mapping = { + "tse": ("https://tagscriptengine.readthedocs.io/en/latest/", None), +} + +default_role = "any" diff --git a/docs/credits.rst b/docs/credits.rst new file mode 100644 index 00000000..23f19e15 --- /dev/null +++ b/docs/credits.rst @@ -0,0 +1,9 @@ +======= +Credits +======= + +Thank you to the following users who contributed to this documentation! + +* **PhenoM4n4n** ``phenom4n4n`` +* **sravan** ``sravan#0001`` +* **Anik** ``aniksarker_21`` diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..c4ca815b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,63 @@ +.. Phen-Cogs documentation master file, created by + sphinx-quickstart on Sat Jan 9 12:47:01 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Phen-Cogs's documentation! +===================================== + +.. image:: https://i.imgur.com/dIOX12K.png + :target: https://github.com/phenom4n4n/phen-cogs + :alt: Phen-Cogs + +.. image:: https://discordapp.com/api/guilds/631306089366945821/widget.png?style=shield + :target: https://discord.gg/cGJ8JmX + :alt: Discord Server + +.. image:: https://img.shields.io/pypi/pyversions/Red-Discordbot + :target: https://www.python.org/downloads + :alt: PyPI - Python Version + +.. image:: https://img.shields.io/badge/discord-py-blue.svg + :target: https://github.com/Rapptz/discord.py + :alt: discord.py + +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/ambv/black + :alt: Code Style: Black + +.. image:: https://readthedocs.org/projects/phen-cogs/badge/?version=latest + :target: https://phen-cogs.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + +.. toctree:: + :maxdepth: 2 + :caption: Tags Documentation + + tags/blocks + tags/tse_blocks + tags/default_variables + tags/parsing_blocks + tags/example_tags + tags/owner_guide + +.. toctree:: + :maxdepth: 2 + :caption: SlashTags Documentation + + slashtags/slashtags + slashtags/slash_arguments + slashtags/context_menus + slashtags/example_slashtags + +.. toctree:: + :caption: Credits + + credits + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..922152e9 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..8a46053a --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,8 @@ +beautifulsoup4 +rapidfuzz +recommonmark +Red-DiscordBot +Sphinx +sphinx_rtd_theme +tabulate +AdvancedTagScriptEngine diff --git a/docs/tags/blocks.rst b/docs/tags/blocks.rst new file mode 100644 index 00000000..e868fa92 --- /dev/null +++ b/docs/tags/blocks.rst @@ -0,0 +1,74 @@ +==== +Tags +==== + +Tags come with the ability to create powerful custom commands through the usage of tag blocks. +The basic block begins with a ``{`` and ends with an ``}``. +More advanced blocks may contain after the block declaration ``()`` to specify a parameter or a ``:`` to specify a payload. + +Block Syntax +------------ + +``{block(parameter):payload}`` + +``[arg]`` = Optional + +```` = Required + +Usage +----- +.. note:: ``[p]`` is your prefix. + +Add a tag using the following command:: + + [p]tag add mytag Hello world! + +Invoke the tag with your bot prefix and the tag's name as if it were a command:: + + [p]mytag + +The bot will then respond with the stored tag content:: + + Hello world! + +^^^^^^^^^^^^^^^^^ +Default Variables +^^^^^^^^^^^^^^^^^ + +Tags come with built-in variable blocks you can access for more information about the invocation context. +These are: + +* ``args`` +* ``author`` | ``user`` +* ``target`` | ``member`` +* ``channel`` +* ``guild`` | ``server`` + +You can see attributes available using these blocks in :doc:`default_variables`. + +Below is an example tag that returns info related to the tag author. :: + + [p]tag add authorinfo Username: **{author}** + ID: **{author(id)}** + Creation Date: **{author(created_at)}** + Bot: **{author(bot)}** + +The ``args`` block can be useful for customizing tags and works well with the :ref:`Command Block`. +Simple echo command that validates if args were provided:: + + [p]tag add echo {if({args}==):You must provide text to echo.|{args}} + +Here's a tag that uses the default variable blocks as well as the :ref:`If Block`:: + + [p]tag add startertag Hi, this is an example of a tag. + This tag will now invoke a ping command. + {c:ping} + {delete({args(0)}==delete)} + {embed({ + "title":"The server this was invoked on was {server}.", + "description":"{if({args}==):You did not provide any arguments for this tag|The arguments provided were: `{args}`}", + "thumbnail":{"url":"{guild(icon)}"}, + "author":{"name":"{author} invoked this tag.","icon_url":"{author(avatar)}"}, + "color":2105893, + "footer":{"icon_url":"{author(avatar)}","text":"{target} is the target of this tag."} + })} diff --git a/docs/tags/default_variables.rst b/docs/tags/default_variables.rst new file mode 100644 index 00000000..f15155bc --- /dev/null +++ b/docs/tags/default_variables.rst @@ -0,0 +1,100 @@ +.. role:: python(code) + :language: python + +================= +Default Variables +================= + +The following blocks will be present and accessable as defaults when running any tag. + +-------------- +Meta Variables +-------------- + +Meta variables reference meta attributes about the tag invocation. + +^^^^^^^^^^ +Args Block +^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.StringAdapter + + The ``{args}`` block represents the arguments passed after the tag name when invoking + a tag. If no parameter is passed, it returns all the text after the invocation name. + If an index is passed, it will split the arguments into a list by the given splitter, + and return the word at that index. The default splitter is a " ". + + **Usage:** ``{args([index]):[splitter]>}`` + + **Payload:** splitter + + **Parameter:** index + + **Examples:** + + In the following examples, assume the tag's name is ``argstag`` and the message + content is ``[p]argstag My dog is cute! Would you like to see a photo?``. :: + + {args} + # My dog is cute! Would you like to see a photo? + + {args(1)} + # My + + {args(2):!} + # Would you like to see a photo? + +^^^^^^^^^^ +Uses Block +^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.IntAdapter + + The ``{uses}`` block returns the number of times a tag has been used. + + **Usage:** ``{uses}`` + + **Payload:** None + + **Parameter:** None + + **Examples:** :: + + {uses} + # 1 + +------------------------ +Discord Object Variables +------------------------ + +These blocks reference Discord objects from the tag invocation context. + +^^^^^^^^^^^^ +Author Block +^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.MemberAdapter + +^^^^^^^^^^^^ +Target Block +^^^^^^^^^^^^ + + The ``{target}`` block follows the same usage and has the same attributes as the + :ref:`Author Block`, but it defaults to the mentioned user in the tag + invocation message if any users are mentioned, or the tag author. + + **Usage:** ``{target}`` + + **Aliases:** ``{member}`` + +^^^^^^^^^^^^^ +Channel Block +^^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.ChannelAdapter + +^^^^^^^^^^^^ +Server Block +^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.GuildAdapter diff --git a/docs/tags/example_tags.rst b/docs/tags/example_tags.rst new file mode 100644 index 00000000..f11501e7 --- /dev/null +++ b/docs/tags/example_tags.rst @@ -0,0 +1,54 @@ +============ +Example Tags +============ + +The following tags listed show examples of using tagscript blocks. + +Context Variables Example +------------------------- + +The following tag shows an example of using the various attributes listed in :doc:`default_variables`. + +:: + + [p]tag + introduce Hi {user(nick)}, welcome to **{guild}**! + + __**USER BLOCK USAGE**__ + Your username is {user(name)}, discriminator is {user(discriminator)}, id is {user(id)}. + Your account was created at {user(created_at)} and you joined {guild(name)} on {user(joined_at)}. + The color for your highest role is {user(color)}. + + __**SERVER BLOCK USAGE**__ + The id of this server is {server(id)}, and it was created at {server(created_at)}. + *Some stats about the server:* + Member count: {server(member_count)} + Human Count: {server(humans)} + Bot Count: {server(bots)} + Additional Info about Server: {server(description)} + + {server(random)} is a just random member of the server you might want to say hi. + + __**CHANNEL BLOCK USAGE**__ + The channel you are using this tag in is {channel(name)} and channel id is {channel(id)}. + Alternatively you could use this attribute in your tags to jump to other channels {channel(mention)} + The channel was created at {channel(created_at)} and the NSFW status of this channel is: {channel(nsfw)} + __*Channel Topic:*__ {channel(topic)} + +Information Storage Example +--------------------------- + +This simple tag shows how to store repeated/informational text. This tag has often been used in a +support server. + +:: + + [p] tag + ss Please send a screenshot. It’s much easier to figure out your problem if we can see what went wrong. + +Command Alias Example +--------------------- + +The following tag is a simple example of using a tag to add an alias to a command. + +:: + + [p]tag add gstart {c:giveaway start {args}} diff --git a/docs/tags/owner_guide.rst b/docs/tags/owner_guide.rst new file mode 100644 index 00000000..a17cddb3 --- /dev/null +++ b/docs/tags/owner_guide.rst @@ -0,0 +1,92 @@ +======================== +Tags Owner Configuration +======================== + +This page details some of the configurability options to Bot owners using the Tags cog. + +These settings can be applied with the ``[p]tagset`` group command, and viewed with +``[p]tagset settings``. + +------------- +Custom Blocks +------------- + +For developers who wish to add custom blocks to the TagScript engine, Tags has built in commands +to add blocks without editing the cog. + +Start off with the ``[p]tagset block add `` command. The code passed must subclass +:class:`TagScriptEngine.Block` and return the subclass. Here's an example of a block that returns +a random duck image :: + + [p]tagset block add duck ```py + import aiohttp + + class RandomDuck(tse.Block): + ACCEPTED_NAMES = ("duck",) + + async def process(self, ctx: tse.Context): + async with aiohttp.ClientSession() as session: + async with session.get("https://random-d.uk/api/v2/random") as resp: + data = await resp.json() + return data["url"] + + return RandomDuck + ``` + +When a user runs a tag with a ``duck`` block, it will return a random duck image such as :: + + [p]tag + randomduck {duck} + [p]randomduck + # https://random-d.uk/api/121.jpg + +One thing to note in the above example is that the `RandomDuck.process` method is asynchronous. +By default, the Tags interpreter doesn't support asynchronous blocks, but asynchronous parsing +can be enabled as detailed in :ref:`Asynchronous Interpreter`. + +Custom blocks can be viewed with ``[p]tagset block list`` or ``[p]tagset block show ``. +They can be deleted with ``[p]tagset block remove ``, and edited by simply re-adding a +block with the same name. + +^^^^^^^^^^^^^^^^^^^^^^^^ +Custom Block Environment +^^^^^^^^^^^^^^^^^^^^^^^^ + +The following global scope variables are available when compiling custom block code: + ++-------------+--------------------------------------+ +| Name | Value | ++=============+======================================+ +| ``tse`` | The TagScriptEngine module. | ++-------------+--------------------------------------+ +| ``asyncio`` | The standard library asyncio module. | ++-------------+--------------------------------------+ +| ``bot`` | The bot object. | ++-------------+--------------------------------------+ +| ``tags`` | The Tags cog object. | ++-------------+--------------------------------------+ + +------------------------ +Asynchronous Interpreter +------------------------ + +By default, the Tags interpreter only supports synchronous blocks and methods. However, in order to +support custom blocks with asynchronous code and avoid blocking tags, bot owners can enable +the asynchronous interpreter with ``[p]tagset async True``. Synchronous blocks will still parse +normally through the interpreter. + +------------- +Dot Parameter +------------- + +TagScript block parsing can be changed to identify parameters with ``.`` rather than ``()``. +This "dot-parameter" style parsing is similar to other formatting parsers, such as the one used in +**CustomCom**. Enabling this with ``[p]tagset dotparam`` will have the following behavior: + +:: + + {server.name} + # Red - Discord Bot + + # dot parameter disabled + {server(name)} + # Red - Discord Bot diff --git a/docs/tags/tse_blocks.rst b/docs/tags/tse_blocks.rst new file mode 100644 index 00000000..831c88e2 --- /dev/null +++ b/docs/tags/tse_blocks.rst @@ -0,0 +1,103 @@ +====================== +TagScriptEngine Blocks +====================== + +----------- +Core Blocks +----------- + +^^^^^^^^^^^^^^^^ +Assignment Block +^^^^^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.AssignmentBlock + +^^^^^^^^^^^^ +Random Block +^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.RandomBlock + +^^^^^^^^^^ +Math Block +^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.MathBlock + +^^^^^^^^^^^ +Range Block +^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.RangeBlock + +-------------- +Control Blocks +-------------- + +^^^^^^^^ +If Block +^^^^^^^^ + +.. autoclass:: TagScriptEngine.IfBlock + +^^^^^^^^^^^ +Break Block +^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.BreakBlock + +^^^^^^^^^ +All Block +^^^^^^^^^ + +.. autoclass:: TagScriptEngine.AllBlock + +^^^^^^^^^ +Any Block +^^^^^^^^^ + +.. autoclass:: TagScriptEngine.AnyBlock + +^^^^^^^^^^^^^^^^^ +Fifty-fifty Block +^^^^^^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.FiftyFiftyBlock + +^^^^^^^^^^ +Stop Block +^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.StopBlock + +------------- +String Blocks +------------- + +^^^^^^^^^^^^^^^ +Replace Block +^^^^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.ReplaceBlock + +^^^^^^^^^^^^^^^ +URLEncode Block +^^^^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.URLEncodeBlock + +-------------------- +Miscellaneous Blocks +-------------------- + +^^^^^^^^^^^^^^ +Strftime Block +^^^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.StrfBlock + +^^^^^^^^^^^^^^^ +Substring Block +^^^^^^^^^^^^^^^ + +.. autoclass:: TagScriptEngine.SubstringBlock