From effd719434826e2053ff523f54eeb368bf5d21b5 Mon Sep 17 00:00:00 2001 From: Phil Date: Sun, 27 Aug 2023 09:10:53 +0200 Subject: [PATCH] docs: refactored page links (#808) --- docpages/01_frequently_asked_questions.md | 6 +++--- docpages/02_disdppgloss.md | 2 +- docpages/03_installing.md | 2 +- docpages/04_building_a_bot.md | 2 +- docpages/05_example_programs.md | 2 +- docpages/06_advanced_reference.md | 2 +- docpages/INDEX.md | 14 +++++++------- .../advanced_reference/automating-with-jenkins.md | 2 +- docpages/advanced_reference/coroutines.md | 6 +++--- docpages/advanced_reference/separate-events.md | 2 +- .../detecting-messages.md | 2 +- docpages/make_a_bot/clion.md | 2 +- docpages/make_a_bot/windows_wsl.md | 2 +- 13 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docpages/01_frequently_asked_questions.md b/docpages/01_frequently_asked_questions.md index f8eb6ccbba..7920108327 100644 --- a/docpages/01_frequently_asked_questions.md +++ b/docpages/01_frequently_asked_questions.md @@ -1,4 +1,4 @@ -# Frequently Asked Questions (FAQ) +\page frequently-asked-questions Frequently Asked Questions (FAQ) [TOC] @@ -99,8 +99,8 @@ Depending on which Raspberry Pi version you have, you will need to download a di ## Are other ARM devices supported? Yes! We have confirmed that the D++ deb file will successfully install and operate on various forms of cellphone or non-pi ARM devices. If you get it working on any other devices please let us know and we can build a compatibility chart. -## Can I run a D++ bot in repl.it? -Yes! You can indeed run your bot in a repl.it container. [You can find a ready to go demo repl here](https://replit.com/@braindigitalis/dpp-demo-bot). We also have a [guide showing how to do this](https://dpp.dev/building-a-cpp-discord-bot-in-repl.html). +## Can I run a D++ bot in Replit? +Yes! You can indeed run your bot in a replit.com container. [You can find a ready to go demo repl here](https://replit.com/@braindigitalis/dpp-demo-bot). We also have a \ref building-a-cpp-discord-bot-in-repl "guide showing how to do this". ## Why do the "get" functions like "messages_get" return void rather than what I'm after? All the functions that obtain data directly from Discord (as opposed to the cache) perform HTTPS requests and may have to wait, either for the request itself or for their turn in a queue to respect rate limits. As such, it does not make sense that they should return a value, as this would mean they block execution of your event. Instead, each has a lambda, a function handler which receives the result of the request, which you can then read from within that function to get the data you are interested in. Note that this result will arrive on a different thread to the one which made the request. If you instead want the function to return a value, use the methods ending with `_sync` that will block until they have a response. Note that these forms of call will throw an exception on failure. diff --git a/docpages/02_disdppgloss.md b/docpages/02_disdppgloss.md index 70c0d33f8f..773ee12a3c 100644 --- a/docpages/02_disdppgloss.md +++ b/docpages/02_disdppgloss.md @@ -1,4 +1,4 @@ -## A Glossary of Common Discord Terms +\page glossary-of-common-discord-terms A Glossary of Common Discord Terms This is a list of terms that you should know if you want to use D++ (or any other discord library). These terms are not D++ specific, and are commonly used throughout most of the Discord developer community. This list, with a few exceptions, ***is discord specific***, that is to say that this is not a explanation of commonly used C++ terms, it is for people who are not familiar with the terminology of the discord API and libraries themselves. diff --git a/docpages/03_installing.md b/docpages/03_installing.md index 2f45e44007..2d1f439c41 100644 --- a/docpages/03_installing.md +++ b/docpages/03_installing.md @@ -1,4 +1,4 @@ -# Installing D++ +\page installing Installing D++ There are many ways to install D++, either from a package manager, or from source. Please choose your desired option from the list below: diff --git a/docpages/04_building_a_bot.md b/docpages/04_building_a_bot.md index 5cd1c62625..6cb0e13509 100644 --- a/docpages/04_building_a_bot.md +++ b/docpages/04_building_a_bot.md @@ -1,4 +1,4 @@ -# Creating a Discord Bot +\page creating-a-discord-bot Creating a Discord Bot If you are wanting to build a bot using C++, you're in the right place! The fast and easy tutorials below will guide you through how to build a bot using the D++ library on either a UNIX-like (e.g. Linux) system with CMake or with Windows using Visual Studio 2019. diff --git a/docpages/05_example_programs.md b/docpages/05_example_programs.md index f2a1a72ef0..19a798271a 100644 --- a/docpages/05_example_programs.md +++ b/docpages/05_example_programs.md @@ -1,4 +1,4 @@ -# Example Programs +\page example-programs Example Programs There are example programs here for all skill levels demonstrating a great many features of the bot. New examples are added frequently, please check regularly for new content. diff --git a/docpages/06_advanced_reference.md b/docpages/06_advanced_reference.md index af3c994a62..8292b7cbe0 100644 --- a/docpages/06_advanced_reference.md +++ b/docpages/06_advanced_reference.md @@ -1,4 +1,4 @@ -# Advanced Reference +\page advanced-reference Advanced Reference * \subpage clusters-shards-guilds "Clusters, Shards and Guilds" * \subpage thread-model "Thread Model" diff --git a/docpages/INDEX.md b/docpages/INDEX.md index ca7e22743f..7d4e93f919 100644 --- a/docpages/INDEX.md +++ b/docpages/INDEX.md @@ -36,10 +36,10 @@ You can find further releases in other architectures and formats or the source c * Efficient caching system for guilds, channels, guild members, roles, users * Sharding and clustering (Many shards, one process: specify the number of shards, or let the library decide) * Highly optimised ETF (Erlang Term Format) support for very fast websocket throughput (*no other C++ Discord library has this!*) -* [Slash Commands/Interactions support](https://dpp.dev/slashcommands.html) -* [Voice support](https://dpp.dev/soundboard.html) (sending **and** receiving audio) +* \ref slashcommands "Slash Commands/Interactions support" +* \ref soundboard "Voice support" (sending **and** receiving audio) * The entire Discord API is available for use in the library -* Stable [Windows support](https://dpp.dev/buildwindows.html) +* Stable \ref buildwindows "Windows support" * Ready-made compiled packages for Windows, Raspberry Pi (ARM64/ARM7/ARMv6), Debian x86/x64 and RPM based distributions * Highly scalable for large amounts of guilds and users @@ -63,10 +63,10 @@ The library should work fine on other operating systems as well, and if you run ## Getting started * [GitHub Repository](https://github.com/brainboxdotcc/DPP) * [Discord Server](https://discord.gg/dpp) -* [Frequently Asked Questions](/md_docpages_01_frequently_asked_questions.html) -* [Installing D++](/md_docpages_01_installing.html) -* [Example Programs](/md_docpages_03_example_programs.html) -* [Commonly used terms](/md_docpages_disdppgloss.html) +* \ref frequently-asked-questions "Frequently Asked Questions" +* \ref installing "Installing D++" +* \ref example-programs "Example Programs" +* \ref glossary-of-common-discord-terms "Commonly used terms" ## Architecture * \ref clusters-shards-guilds diff --git a/docpages/advanced_reference/automating-with-jenkins.md b/docpages/advanced_reference/automating-with-jenkins.md index a191ee3560..cb9ccfc718 100644 --- a/docpages/advanced_reference/automating-with-jenkins.md +++ b/docpages/advanced_reference/automating-with-jenkins.md @@ -1,6 +1,6 @@ \page automating-with-jenkins Automating your bot with Jenkins -\note This page does NOT go into explaining how to install Jenkins, nor how to initially setup Jenkins. This is a tutorial for the CMake version with Linux (more specifically Ubuntu 22.04 LTS). If you don't know how to use CMake or you don't use CMake for your bot (and would like to) then please visit [Building a Discord Bot using CMake/Unix](/buildcmake.html). If you wish to automate this tutorial from GitHub pushes then you can simply download the GitHub plugin for Jenkins, set that up and this tutorial will still work as this tutorial will only build what it can see! +\note This page does NOT go into explaining how to install Jenkins, nor how to initially setup Jenkins. This is a tutorial for the CMake version with Linux (more specifically Ubuntu 22.04 LTS). If you don't know how to use CMake or you don't use CMake for your bot (and would like to) then please visit \ref buildcmake. If you wish to automate this tutorial from GitHub pushes then you can simply download the GitHub plugin for Jenkins, set that up and this tutorial will still work as this tutorial will only build what it can see! ### Getting started diff --git a/docpages/advanced_reference/coroutines.md b/docpages/advanced_reference/coroutines.md index 0a1b2e50ef..a6802f134a 100644 --- a/docpages/advanced_reference/coroutines.md +++ b/docpages/advanced_reference/coroutines.md @@ -6,7 +6,7 @@ Introduced in C++20, coroutines are the solution to the impracticality of callbacks. In short, a coroutine is a function that can be paused and resumed later. They are an extremely powerful alternative to callbacks for asynchronous APIs in particular, as the function can be paused when waiting for an API response, and resumed when it is received. -Let's revisit [attaching a downloaded file](/attach-file.html), but this time with a coroutine: +Let's revisit \ref attach-file "attaching a downloaded file", but this time with a coroutine: ~~~~~~~~~~~~~~~{.cpp} @@ -51,11 +51,11 @@ In order to be a coroutine, a function has to return a special type with special When using a `co_*` function such as `co_message_create`, the request is sent immediately and the returned dpp::async can be `co_await`-ed, at which point the coroutine suspends (pauses) and returns back to its caller; in other words, the program is free to go and do other things while the data is being retrieved and D++ will resume your coroutine when it has the data you need, which will be returned from the `co_await` expression. -\attention You may hear that coroutines are "writing async code as if it was sync", while this is sort of correct, it may limit your understanding and especially the dangers of coroutines. I find **they are best thought of as a shortcut for a state machine**. If you've ever written one, you know what this means. Think of the lambda as *its constructor*, in which captures are variable parameters. Think of the parameters passed to your lambda as data members in your state machine. References are kept as references, and by the time the state machine is resumed, the reference may be dangling : [this is not good](/lambdas-and-locals.html)! As a rule of thumb when making coroutines, **always prefer taking parameters by value and avoid lambda capture**. +\attention You may hear that coroutines are "writing async code as if it was sync", while this is sort of correct, it may limit your understanding and especially the dangers of coroutines. I find **they are best thought of as a shortcut for a state machine**. If you've ever written one, you know what this means. Think of the lambda as *its constructor*, in which captures are variable parameters. Think of the parameters passed to your lambda as data members in your state machine. References are kept as references, and by the time the state machine is resumed, the reference may be dangling : \ref lambdas-and-locals "this is not good"! As a rule of thumb when making coroutines, **always prefer taking parameters by value and avoid lambda capture**. ### Several steps in one -\note The next example assumes you are already familiar with how to use [slash commands](/firstbot.html), [parameters](/slashcommands.html), and [sending files through a command](/discord-application-command-file-upload.html). +\note The next example assumes you are already familiar with how to use \ref firstbot "slash commands", \ref slashcommands "parameters", and \ref discord-application-command-file-upload "sending files through a command". Here is another example of what is made easier with coroutines, an "addemoji" command taking a file and a name as a parameter. This means downloading the emoji, submitting it to Discord, and finally replying, with some error handling along the way. Normally we would have to use callbacks and some sort of object keeping track of our state, but with coroutines, it becomes much simpler: diff --git a/docpages/advanced_reference/separate-events.md b/docpages/advanced_reference/separate-events.md index fc5dcc79de..dc2764cbca 100644 --- a/docpages/advanced_reference/separate-events.md +++ b/docpages/advanced_reference/separate-events.md @@ -2,7 +2,7 @@ If you're someone that loves file organisation (or you hate how cluttered your `main.cpp` has become) then you may be interested in moving events into separate classes outside of the `main.cpp` file. This is a great way to improve readability and can be helpful in many cases! For example, you can have two classes on the same event, except one could be reading messages for spam and one could be reading messages for bad words! -In this tutorial, we'll be taking the [Listening to messages](/detecting-messages.html) example and moving the `on_message_create` event into a different class. +In this tutorial, we'll be taking the \ref detecting-messages "Listening to messages" example and moving the `on_message_create` event into a different class. To get started, you can create a folder called `listeners` inside `src` (where your `main.cpp` is) if you'd like to put it there! We'll be doing exactly that so, if you'd like to stick along with the tutorial, get creating that folder! diff --git a/docpages/example_programs/interactions_and_components/detecting-messages.md b/docpages/example_programs/interactions_and_components/detecting-messages.md index 82e2c9ac5b..a3278c85a5 100644 --- a/docpages/example_programs/interactions_and_components/detecting-messages.md +++ b/docpages/example_programs/interactions_and_components/detecting-messages.md @@ -2,7 +2,7 @@ Sometimes, you may want to listen out for a message, rather than a command. This could be used for many cases like a spam filter, a bot that would respond to movie quotes with gifs, or a chat bot! However, in this page, we'll be using this to create a moderation filter (detect bad words). -\warning As of August 30th, 2022, Discord made Message Content a privileged intent. Whilst this means you can still use prefixed messages as commands, Discord does not encourage this and heavily suggests you use [slash commands](/slashcommands.html). If you wish to create commands, use [slash commands](/slashcommands.html), not messages. +\warning As of August 30th, 2022, Discord made Message Content a privileged intent. Whilst this means you can still use prefixed messages as commands, Discord does not encourage this and heavily suggests you use \ref slashcommands "slash commands". If you wish to create commands, use \ref slashcommands "slash commands", not messages. ~~~~~~~~~~{.cpp} #include diff --git a/docpages/make_a_bot/clion.md b/docpages/make_a_bot/clion.md index 3d5ceeadb2..6aadb74a2d 100644 --- a/docpages/make_a_bot/clion.md +++ b/docpages/make_a_bot/clion.md @@ -73,7 +73,7 @@ Then open the "File" menu and click on "Reload CMake Project" to reload the CMak ### Add an example program -The next step is to write the bot. Copy and paste the following [example program](https://dpp.dev/firstbot.html) in the `main.cpp` and set your bot token (see [Creating a Bot Token](https://dpp.dev/creating-a-bot-application.html)): +The next step is to write the bot. Copy and paste the following \ref firstbot "example program" in the `main.cpp` and set your bot token (see \ref creating-a-bot-application): ~~~~~~~~~~~~~~~{.cpp} diff --git a/docpages/make_a_bot/windows_wsl.md b/docpages/make_a_bot/windows_wsl.md index 1ae42e1e83..d811af9bd0 100644 --- a/docpages/make_a_bot/windows_wsl.md +++ b/docpages/make_a_bot/windows_wsl.md @@ -5,7 +5,7 @@ This tutorial teaches you how to create a lightweight environment for D++-develo This Tutorial will use WSL's default distribution, **Ubuntu**! You might use other Distros if you prefer, but keep in mind the setup process might be different! 1. Make sure you have installed your WSL 2 environment properly using [this guide to setup up WSL](https://docs.microsoft.com/en-us/windows/wsl/install) and [this guide to connect to Visual Studio Code](https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode). -2. Now open PowerShell as an Admin and type `wsl` to start up your subsystem. If you want to set up a CMake project (recommended for production bots) now, consider continuing your path of becoming the master of all Discord bots [here](https://dpp.dev/buildcmake.html), otherwise keep following this guide! +2. Now open PowerShell as an Admin and type `wsl` to start up your subsystem. If you want to set up a CMake project (recommended for production bots) now, consider continuing your path of becoming the master of all Discord bots \ref buildcmake "here", otherwise keep following this guide! 3. Go to your home directory using `cd ~` 4. Download the latest build for your Distro using `wget [url here]`. In this guide we will use the latest build for 64 bit Ubuntu: `wget -O libdpp.deb https://dl.dpp.dev/latest` 5. Finally install all required deps and the library using `sudo apt-get install libopus0 && sudo apt-get install -y libopus-dev && sudo apt-get install -y libsodium-dev && sudo dpkg -i libdpp.deb && rm libdpp.deb`