usage.rst

dt, dd { margin-bottom: 0 !important; } <blockquote> <p>&lt;/style&gt;</p> </blockquote> <h1 id="getting-started">Getting Started</h1> <h2 id="command-line">Command Line</h2> <p>There's a few available things from the commandline (CMD) that you can do with VoxelBotUtils. You can run the module either as <code class="sourceCode">python3 -m voxelbotutils</code>, or it's registered as a plain <code class="sourceCode">voxelbotutils</code> to your PATH on install that you can run instead.</p> <div id="cmd_create_config"> <ul> <li><p><code class="sourceCode">$ voxelbotutils create-config</code></p> <blockquote> <ul> <li><code class="sourceCode">bot</code> - this creates a set of bot config files</li> <li><code class="sourceCode">website</code> - this creates a set of website config files</li> <li><code class="sourceCode">all</code> - this creates a set of all available config files</li> </ul> </blockquote></li> </ul> </div> <div id="cmd_run_bot"> <ul> <li><p><code class="sourceCode">$ voxelbotutils run-bot</code></p> <blockquote> <ul> <li><code class="sourceCode">[bot_directory]</code> - the directory that the bot files are located in; defaults to <span class="title-ref">.</span></li> <li><code class="sourceCode">[config_file]</code> - the path to the config file to use; defaults to <span class="title-ref">config/config.toml</span></li> <li><code class="sourceCode">--min [amount]</code> - the minimum shard ID for this instance</li> <li><code class="sourceCode">--max [amount]</code> - the maximum shard ID for this instance</li> <li><code class="sourceCode">--shardcount [amount]</code> - the number of shards that the bot should identify as (not the number of shards for this instance)</li> <li><code class="sourceCode">--loglevel [level]</code> - the <code class="sourceCode">logging.Logger</code> loglevel that you want to start the bot with</li> </ul> </blockquote></li> </ul> </div> <div id="cmd_run_interactions"> <ul> <li><p><code class="sourceCode">$ voxelbotutils run-interactions</code></p> <blockquote> <ul> <li><code class="sourceCode">[bot_directory]</code> - the directory that the bot files are located in; defaults to <span class="title-ref">.</span></li> <li><code class="sourceCode">[config_file]</code> - the path to the config file to use; defaults to <span class="title-ref">config/config.toml</span></li> <li><code class="sourceCode">--host</code> - the host that you want to run the webserver with.</li> <li><code class="sourceCode">--port</code> - the port that you want to run the webserver on.</li> <li><code class="sourceCode">--path</code> - the path that the route should be added as; defaults to <span class="title-ref">/interactions</span></li> <li><code class="sourceCode">--connect</code> - if you want to connect your bot to the gateway as well as running the interactions webserver; shards will be automatically calculated and intents will be set to none.</li> <li><code class="sourceCode">--loglevel [level]</code> - the <code class="sourceCode">logging.Logger</code> loglevel that you want to start the bot with</li> </ul> </blockquote></li> </ul> </div> <div id="cmd_commands"> <ul> <li><p><code class="sourceCode">$ voxelbotutils commands</code></p> <blockquote> <ul> <li><code class="sourceCode">[action]</code> - the action you want to take for your commands - this can be <code class="sourceCode">add</code> or <code class="sourceCode">remove</code></li> <li><code class="sourceCode">[bot_directory]</code> - the directory that the bot files are located in; defaults to <span class="title-ref">.</span></li> <li><code class="sourceCode">[config_file]</code> - the path to the config file to use; defaults to <span class="title-ref">config/config.toml</span></li> <li><code class="sourceCode">--guild [guild_id]</code> - if you want to perform the action for a specific guild, you can specify its ID here</li> </ul> </blockquote></li> </ul> </div> <h2 id="getting-started-with-bots">Getting Started With Bots</h2> <p>To get started you'll first want to make a config file. Fortunately, making one is pretty easy, and can be done via CMD.</p> <div class="sourceCode" id="cb1"><pre lang="bash" class="sourceCode bash"><code class="sourceCode bash"><a class="sourceLine" id="cb1-1" title="1">$ <span class="ex">voxelbotutils</span> create-config bot</a></code></pre></div> <p>Doing this will make a few files and folders:</p> <ul> <li><code class="sourceCode">cogs/ping_command.py</code> - a simple base class that you can copy/paste to build new classes</li> <li><code class="sourceCode">config/config.toml</code> - this is your bot's configuration file</li> <li><code class="sourceCode">config/config.example.toml</code> - this is a git-safe version of your configuration file; you can commit this as you please</li> <li><code class="sourceCode">config/database.pgsql</code> - this file should contain your database schema; it'll be pushed to your bot's database at every startup</li> <li><code class="sourceCode">.gitignore</code> - a default Gitignore file to ignore your configuration file</li> </ul> <h3 id="running-the-bot">Running the Bot</h3> <p>Running the bot is also available via the package at a CMD level.</p> <div class="sourceCode" id="cb2"><pre lang="bash" class="sourceCode bash"><code class="sourceCode bash"><a class="sourceLine" id="cb2-1" title="1">$ <span class="ex">voxelbotutils</span> run-bot</a></code></pre></div> <p>The information in the bot's <code class="sourceCode">config/config.toml</code> file will be used to run it, as well as automatically loading any files found in the <code class="sourceCode">cogs/</code> folder, should they not start with an underscore (eg the file <code class="sourceCode">cogs/test.py</code> would be loaded, but <code class="sourceCode">cogs/_test.py</code> would not).</p> <p>If your database is enabled when you start your bot, the information found in the <code class="sourceCode">config/database.pgsql</code> will be automatically run, so make sure to write your tables as <code class="sourceCode">CREATE TABLE IF NOT EXISTS</code> and put your enum creations in an if statement -</p> <div class="sourceCode" id="cb3"><pre lang="sql" class="sourceCode sql"><code class="sourceCode sql"><a class="sourceLine" id="cb3-1" title="1">DO $$ <span class="cf">BEGIN</span></a> <a class="sourceLine" id="cb3-2" title="2"> <span class="kw">CREATE</span> <span class="kw">TYPE</span> my_type <span class="kw">AS</span> ENUM (<span class="st">&#39;Example 1&#39;</span>, <span class="st">&#39;Example 2&#39;</span>);</a> <a class="sourceLine" id="cb3-3" title="3"><span class="kw">EXCEPTION</span></a> <a class="sourceLine" id="cb3-4" title="4"> <span class="cf">WHEN</span> duplicate_object <span class="cf">THEN</span> <span class="kw">null</span>;</a> <a class="sourceLine" id="cb3-5" title="5"><span class="cf">END</span> $$;</a></code></pre></div> <h3 id="migrating">Migrating</h3> <p>If you're reading this, you <em>probably</em> already have a bot that you want to get using with VoxelBotUtils. Fortunately, migrating is pretty easy. Most base Discord.py classes work by default without alteration, and as such you can just run your existing bot with a VBU config file, and that can be that.</p> <p>If you really want to get things going, you can change all of your <code class="sourceCode">@commands.command()</code> lines to <code class="sourceCode">@voxelbotutils.command()&lt;voxelbotutils.Command&gt;</code>, and any <code class="sourceCode">class MyCog(commands.Cog)</code> to <code class="sourceCode">class MyCog(voxelbotutils.Cog)&lt;voxelbotutils.Cog&gt;</code>, and everything else should pretty much handle itself.</p> <p>Alternatively, some people want to make as few code changes as possible, using only the VoxelBotUtils utilities. That's available too! If you change your bot instance in your current Discord.py code to use <code class="interpreted-text" data-role="class">voxelbotutils.MinimalBot</code> then everything else is drag and drop as usual. This change is necessary to make use of the changes to Discord.py's <code class="interpreted-text" data-role="class">discord.abc.Messageable</code> (which include buttons and ephemeral messages). If there are certain extensions that you wish to load yourself from VoxelBotUtils, you can do that with <code class="sourceCode">bot.load_extension("voxelbotutils.cogs.[NAME]")</code>.</p> <h2 id="getting-started-with-websites">Getting Started With Websites</h2> <p>To get started, you'll need to make a configuration file that VBU can use. The library is nice enough to do this for you if you run the module via the commandline:</p> <div class="sourceCode" id="cb4"><pre lang="bash" class="sourceCode bash"><code class="sourceCode bash"><a class="sourceLine" id="cb4-1" title="1">$ <span class="ex">voxelbotutils</span> create-config website</a></code></pre></div> <p>Doing this will make a few files and folders:</p> <ul> <li><code class="sourceCode">website/frontend.py</code> - a simple set of frontend routes</li> <li><code class="sourceCode">website/backend.py</code> - a simple set of backend routes</li> <li><code class="sourceCode">website/static/</code> - a folder for all of your static files</li> <li><code class="sourceCode">website/templates/</code> - a folder for your Jinja2 templates</li> <li><code class="sourceCode">config/website.toml</code> - this is your bot's configuration file</li> <li><code class="sourceCode">config/website.example.toml</code> - this is a git-safe version of your configuration file; you can commit this as you please</li> <li><code class="sourceCode">config/database.pgsql</code> - this file should contain your database schema</li> <li><code class="sourceCode">.gitignore</code> - a default Gitignore file to ignore your configuration file</li> </ul> <h3 id="running-the-website">Running the Website</h3> <p>You can write your website routes in the <code class="sourceCode">frontend.py</code> and <code class="sourceCode">backend.py</code> files (as well as any other files you specify in <code class="interpreted-text" data-role="attr">your config&lt;WebsiteConfig.routes&gt;</code>) and run your website from CMD.</p> <div class="sourceCode" id="cb5"><pre lang="bash" class="sourceCode bash"><code class="sourceCode bash"><a class="sourceLine" id="cb5-1" title="1">$ <span class="ex">voxelbotutils</span> run-website</a></code></pre></div>