diff --git a/changelog.d/1734.docs.1.rst b/changelog.d/1734.docs.1.rst new file mode 100644 index 000000000..3995729ef --- /dev/null +++ b/changelog.d/1734.docs.1.rst @@ -0,0 +1,2 @@ +Start the user guides covering cogs and the user interface of the bot. This +includes, for now, a "Getting started" guide. diff --git a/docs/.resources/code-grant.png b/docs/.resources/code-grant.png new file mode 100644 index 000000000..764f202bd Binary files /dev/null and b/docs/.resources/code-grant.png differ diff --git a/docs/.resources/instances-ssh-button.png b/docs/.resources/instances-ssh-button.png new file mode 100644 index 000000000..7c678bd89 Binary files /dev/null and b/docs/.resources/instances-ssh-button.png differ diff --git a/docs/.resources/red-console.png b/docs/.resources/red-console.png new file mode 100644 index 000000000..fdfcfc68e Binary files /dev/null and b/docs/.resources/red-console.png differ diff --git a/docs/.resources/ssh-output.png b/docs/.resources/ssh-output.png new file mode 100644 index 000000000..7391a214b Binary files /dev/null and b/docs/.resources/ssh-output.png differ diff --git a/docs/Makefile b/docs/Makefile index 49c3b9536..a192210be 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = python -msphinx +SPHINXBUILD = python3 -msphinx SPHINXPROJ = Red-DiscordBot SOURCEDIR = . BUILDDIR = _build @@ -17,4 +17,4 @@ help: # 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) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/autostart_systemd.rst b/docs/autostart_systemd.rst index b8d522ccb..1af55e478 100644 --- a/docs/autostart_systemd.rst +++ b/docs/autostart_systemd.rst @@ -1,4 +1,4 @@ -.. systemd service guide +.. _systemd-service-guide: ============================================== Setting up auto-restart using systemd on Linux diff --git a/docs/conf.py b/docs/conf.py index 18d2855a9..98ba46e63 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -92,6 +92,9 @@ todo_include_todos = False # Role which is assigned when you make a simple reference within backticks default_role = "any" +# Includes substitutions for all files +with open("prolog.txt", "r") as file: + rst_prolog = file.read() # -- Options for HTML output ---------------------------------------------- diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 000000000..6e45d8215 --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,360 @@ +.. don't forget to set permissions hyperlink + + commands links + guide links + +.. _getting-started: + +=============== +Getting started +=============== + +If you recently installed Red, you should read this. +This is a quick start guide for a general usage. + +.. note:: + + If you haven't installed Red, please do it by following + the :ref:`installation guides
`. + +Assuming you correctly installed Red, you should have a +window like this: + +.. image:: .resources/red-console.png + +.. _gettings-started-invite: + +------------------------- +Invite Red to your server +------------------------- + +When started, the console will show you ``Invite URL`` (here at +the bottom of the screenshot). +Paste the link into your browser and select the server you want +to invite the bot in, like any other bot. + +.. note:: You need the ``Manage server`` permission to add bots. + +Complete the captcha, it should tell you ``Authorized!`` and you +should see your bot in the members list. + +.. attention:: + If Discord shows ``Bot requires code grant``, please untick this + option in your token settings + + .. image:: .resources/code-grant.png + +.. _getting-started-interact: + +----------------- +Interact with Red +----------------- + +As a chatbot, you interact with Red via the Discord text channels +(not from the command prompt). To send commands to the bot, you will have to +use the prefix you set before, followed by the command you want to use. For +example, if your prefix is ``!``, you will execute your command like this: +``!ping``. + +.. note:: Since the prefix can be anything, it'll be referenced as ``[p]`` + in documentations. + +.. _getting-started-commands: + +~~~~~~~~~~~~ +The commands +~~~~~~~~~~~~ + +The command you're going to use the most is help. That command will +show you **all of the available commands** of the bot with a small description. + +.. code-block:: none + + [p]help + +.. tip:: The message is generated dynamically and users will only see the + commands they can use. You can change what commands users can use with the + permissions cog. + +You can also pick a command to get its detailed description and the +parameters. + +.. code-block:: none + + [p]help command + +The parameters are shown as enclosed in ``< >`` if they're required, or +``[ ]`` if optional. +As an example, the ban command will show this in the help message, assuming +your prefix is ``!``: +``Syntax: !ban [days] [reason]`` + +This means that it is necessary to provide ``user``. However, the +``days`` value (number of messages to delete) is optional, as well as +the ``reason`` value, used for the modlog. + +You can use help to show the **categories** too, generally called cogs. +Just do something like this (notice the capitalization): + +.. code-block:: none + + [p]help YourCategory + +Help also shows **command groups**. They are group of commands. +To get the description of a subcommand, type this: + +.. code-block:: none + + [p]help commandgroup subcommand + +When using subcommands, you also need to specify the command group. +As an example, ``cleanup`` has 6 subcommands. If you want +to use one, do it like this: ``[p]cleanup messages 10`` + +.. _getting-started-cogs: + +---- +Cogs +---- + +Red is built with cogs, fancy term for plugins. They are +modules that enhance the Red functionalities. They contain +commands to use. + +Red comes with 19 cogs containing the basic features, such +as moderation, utility, music, streams... + +You can see your loaded and unloaded cogs with the ``[p]cogs`` +command. By default, all cogs will be unloaded. + +You can load or unload a cog by using the load or unload command + +.. code-block:: none + + [p]load cogname + [p]unload cogname + +.. tip:: You can load and unload multiple cogs at once: + + .. code-block:: none + + [p]load cog1 cog2 ... + +You can enable and disable everything you want, which means you can +customize Red how you want! + +.. _getting-started-community-cogs: + +~~~~~~~~~~~~~~ +Community cogs +~~~~~~~~~~~~~~ + +There's an entire `community `_ that contributes +to Red. Those contributors make additional cogs for you to use. You can +download them using the downloader cog. + +You can start using the downloader cog by loading it: ``[p]load downloader`` + +You can find cogs by searching on ``cogs.red``. Find whatever you want, +there are hundreds of cogs available! + +.. note:: ``cogs.red``, the website that list all of the cogs is not + ready for v3 yet. For now, you can refer to `this post + `_. + +.. 26-cogs not available, let's use my repo :3 + +Cogs comes with repositories. A repository is a container of cogs +that you can install. Let's suppose you want to install the ``say`` +cog from the repository ``Laggrons-Dumb-Cogs``. You'll first need +to install the repository. + +.. code-block:: none + + [p]repo add Laggrons-Dumb-Cogs https://github.com/retke/Laggrons-Dumb-Cogs + +.. note:: You may need to specify a branch. If so, add its name after the link. + +Then you can add the cog + +.. code-block:: none + + [p]cog install Laggrons-Dumb-Cogs say + +Now the cog is installed, but not loaded. You can load it using the ``[p]load`` +command we talked about before. + +.. _getting-started-permissions: + +----------- +Permissions +----------- + +Red works with different levels of permissions. Every cog defines +the level of permission needed for a command. + +~~~~~~~~~ +Bot owner +~~~~~~~~~ + +The bot owner can access all commands on every guild. He can also use +exclusive commands that can interact with the global settings +or system files. + +*You* are the owner by default. + +~~~~~~~~~~~~ +Server owner +~~~~~~~~~~~~ + +The server owner can access all commands on his guild, except the global +ones or those who can interact with system files (available for the +bot owner). + +~~~~~~~~~~~~~ +Administrator +~~~~~~~~~~~~~ + +The administrator is defined by its roles. You can set multiple admin roles +with the ``[p]addadminrole`` and ``[p]removeadminrole`` commands. + +For example, in the mod cog, an admin can use the ``[p]modset`` command +which defines the cog settings. + +~~~~~~~~~ +Moderator +~~~~~~~~~ + +A moderator is a step above the average users. You can set multiple moderator +roles with the ``[p]addmodrole`` and ``[p]removemodrole`` commands. + +For example, in the mod cog (again), a mod will be able to mute, kick and ban; +but he won't be able to modify the cog settings with the ``[p]modset`` command. + +.. tip:: + If you don't like the default permission settings for some commands or + if want to restrict a cog or a command to a channel/member, you can use + the permissions cog. + +.. _getting-started-hosting: + +------- +Hosting +------- + +If you are hosting Red on your personal computer, you will soon notice that +if you close the window or if you shut down you computer, Red will be offline. +She needs an environment to work and respond. + +You can try to host Red somewhere she will always be online, like on a virtual +private server (VPS) or on a personal server (e.g. Raspberry Pi). + +If you want to do it, follow these steps. + +.. warning:: + Before trying to host Red on a Linux environment, you need to know the + basics of the Unix commands, such as navigating the system files or use + a terminal text editor. + + You should follow `this guide + `_ + from DigitalOcean which will introduce you to the Linux basics. + +1. **Find a host** + + You need to find a server to host Red. You can rent a VPS (it can be free) + on an online service. Please check :ref:`this list ` for + quality VPS providers. + + You can also buy a Raspberry Pi (~$20), which is a micro-computer that will + be able to host Red. The model 3 or above is recommended. + +2. **Install Linux** + + Most of the VPS providers have tools for installing Linux automatically. If + you're a beginner, we recommend **Ubuntu 18**. + + For Raspberry Pi users, just install `Raspbian + `_ on a micro-SD card. + +2.1. **Log in** + + .. note:: This section is for those who have an online server. If you have + a local Linux machine, just open the terminal and skip to the next part. + + As we said before, a VPS is controlled through command line. You will have to + connect to your VPS through a protocol called SSH. + + .. image:: .resources/instances-ssh-button.png + + On your host page (here, it is Google Cloud), find the SSH button and click on + it. You will be connected to your server with command line. You should see + something like this. + + .. image:: .resources/ssh-output.png + + .. note:: Don't forget to type the command ``logout`` to close the SSH properly. + +3. **Install and set up Red** + + Just follow one of the Linux installation guide. We provide guides for the + most used distributions. Check the :ref:`home page
` and search for + your distribution. + +4. **Set up an auto-restart** + + Once you got Red running on your server, it will still shut down if you close + the window. You can set up an auto-restarting system that will create a + side task and handle fatal errors, so you can just leave your server running + and enjoy Red! + + For that, just follow :ref:`this guide `. + +.. _getting-started-userdocs: + +------------------ +User documentation +------------------ + +You will soon start using the Red core cogs. A detailed documentation is +available for every core cog, under the :ref:`How to use
` section. + +The cog guides are formatted the same. They're divided into 3 sections: + +* **Guide** + + This will introduce you to the cog and explain you how it works. + +* **Commands** + + A list of the available commands, with details and arguments. + Each command guide will be formatted like this: + + * **Syntax** + + A line that will show how the command must be invoked, with the arguments. + + .. tip:: If the command show something like ``[lavalinkset|llset]``, that means + you can invoke the command with ``lavalinkset`` or with ``llset``, this is + called an alias. + + * **Description** + + A detailed description of what the command does, with details about how + it must be used. + + * **Arguments** + + A list of all arguments needed (or not) for the command, with more details. + + .. tip:: + Arguments enclosed in ``< >`` means that the argument is **required** + for the command to work. + + Arguments enclosed in ``[ ]`` means that the argument is **optional** + for the command; you can decide to use it or not. + + Arguments followed by ``=something`` means that, if not specified, + the argument will be equal to ``something``. + + For example, ``[days=1]`` in the ``ban`` command means that the number + of days of messages to be deleted will be equal to ``1`` if not + specified. diff --git a/docs/host-list.rst b/docs/host-list.rst new file mode 100644 index 000000000..47398d898 --- /dev/null +++ b/docs/host-list.rst @@ -0,0 +1,81 @@ +.. source: https://gist.github.com/Twentysix26/cb4401c6e507782aa6698e9e470243ed + +.. _host-list: + +============= +VPS providers +============= + +.. note:: + This doc is written for the :ref:`hosting section ` + of the :ref:`getting started ` guide. Please take a look + if you don't know how to host Red on a VPS. + +This is a list of the recommended VPS providers. + +.. warning:: + Please be aware that a Linux server is controlled through a command line. + If you don't know Unix basics, please take a look at `this guide + `_ + from DigitalOcean which will introduce you to the Linux basics. + +------------- +Linux hosting +------------- + ++------------------------------------+------------------------------------------------------+ +|Link |Description | ++====================================+======================================================+ +|`Scaleway |Incredibly cheap but powerful VPSes, owned by | +|`_ |``_, based in Europe. | ++------------------------------------+------------------------------------------------------+ +|`DigitalOcean |US-based cheap VPSes. The gold standard. Locations | +|`_ |available world wide. | ++------------------------------------+------------------------------------------------------+ +|`OVH `_ |Cheap VPSes, used by many people. French and Canadian | +| |locations available. | ++------------------------------------+------------------------------------------------------+ +|`Time4VPS |Cheap VPSes, seemingly based in Lithuania. | +|`_ | | ++------------------------------------+------------------------------------------------------+ +|`Linode `_ |More cheap VPSes! | ++------------------------------------+------------------------------------------------------+ +|`Vultr `_ |US-based, DigitalOcean-like. | ++------------------------------------+------------------------------------------------------+ + +------ +Others +------ + ++-------------------------------------+-----------------------------------------------------+ +|Link | | ++=====================================+=====================================================+ +|`AWS `_ |Amazon Web Services. Free for a year (with certain | +| |limits), but very pricey after that. | ++-------------------------------------+-----------------------------------------------------+ +|`Google Cloud |Same as AWS, but it's Google. | +|`_| | ++-------------------------------------+-----------------------------------------------------+ +|`LowEndBox `_ |A curator for lower specced servers. | ++-------------------------------------+-----------------------------------------------------+ + +------------ +Self-hosting +------------ + +You can always self-host on your own hardware. +A Raspberry Pi 3 will be more than sufficient for small to medium sized bots. + +For bigger bots, you can build your own server PC for usage, or buy a rack +server. Any modern hardware should work 100% fine. + +------------ +Free hosting +------------ + +Google Cloud and AWS both have free tier VPS suitable for small bots. +Additionally, new Google Cloud customers get a $300 credit which is valid +for 12 months. + +Other than that... no. There is no good free VPS hoster, outside of +persuading somebody to host for you, which is incredibly unlikely. diff --git a/docs/index.rst b/docs/index.rst index ab262fbd5..bcec8b9f2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. _main: + Welcome to Red - Discord Bot's documentation! ============================================= @@ -23,6 +25,12 @@ Welcome to Red - Discord Bot's documentation! cog_downloader cog_permissions +.. toctree:: + :maxdepth: 2 + :caption: User guides: + + getting_started + .. toctree:: :maxdepth: 2 :caption: Red Development Framework Reference: @@ -51,6 +59,12 @@ Welcome to Red - Discord Bot's documentation! changelog_3_1_0 +.. toctree:: + :maxdepth: 2 + :caption: Others + + host-list + Indices and tables ================== diff --git a/docs/prolog.txt b/docs/prolog.txt new file mode 100644 index 000000000..3b75c347a --- /dev/null +++ b/docs/prolog.txt @@ -0,0 +1,41 @@ +.. This file will be run at the beginning of all files. + You can add the subsitutions you need. + +.. this is a .txt so sphinx doesn't error because it's + missing in the index + + +.. These are the comments for permissions locks + +.. |owner-lock| replace:: This command is locked to the + :ref:`bot owner `. + +.. |guildowner-lock| replace:: This command is locked to the + :ref:`server owner `. + +.. |admin-lock| replace:: This command is locked to the + :ref:`admin role `. + +.. |mod-lock| replace:: This command is locked to the + :ref:`mod role `. + + +.. This is for describing how a format should be formatted + +.. |quotes| replace:: enclosed in quotes if there are spaces + +.. |role-input| replace:: Please give **the exact role name or ID**, or it won't be detected. + If the role name has spaces, provide it enclosed in quotes like this: ``"my role with spaces"`` + +.. |member-input| replace:: You can either mention the member, provide its ID, its exact name with + the tag or not, or its nickname (|quotes|). + +.. |user-input| replace:: You can either provide the member's ID or its exact name with the tag or + not (|quotes|). + +.. |channel-input| replace:: You can either mention the channel, provide its exact name or its ID. + +.. |vc-input| replace:: You can either provide the voice channel's ID or its exact name, |quotes|. + +.. |color-input| replace:: You can either provide the hexadecimal code of the color, or one of the + colors listed here: :class:`discord.Color`.