diff --git a/.github/labeler.yml b/.github/labeler.yml index 720d0adfe..8f55f9a40 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -167,6 +167,7 @@ - redbot/cogs/trivia/* # Docs - docs/cog_guides/trivia.rst + - docs/guide_trivia_list_creation.rst "Category: Trivia Lists": - redbot/cogs/trivia/data/lists/* "Category: Utility Functions": diff --git a/docs/.resources/trivia/trivia_author.png b/docs/.resources/trivia/trivia_author.png new file mode 100644 index 000000000..389de16d9 Binary files /dev/null and b/docs/.resources/trivia/trivia_author.png differ diff --git a/docs/cog_guides/trivia.rst b/docs/cog_guides/trivia.rst index ca35386c7..3996e29f0 100644 --- a/docs/cog_guides/trivia.rst +++ b/docs/cog_guides/trivia.rst @@ -247,6 +247,11 @@ triviaset custom Manage custom trivia lists. +.. tip:: + + Looking to learn how to create your own trivia lists? + See :ref:`here ` for more information. + .. _trivia-command-triviaset-custom-upload: ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/guide_trivia_list_creation.rst b/docs/guide_trivia_list_creation.rst new file mode 100644 index 000000000..247b00a48 --- /dev/null +++ b/docs/guide_trivia_list_creation.rst @@ -0,0 +1,125 @@ +.. _guide_trivia_list_creation: + +========================== +Trivia List Creation Guide +========================== + +The Trivia cog allows you to create your own "trivia lists", +which are then processed in the cog - allowing you to create as +many questions as you'd like, with easy to use syntax. + +--------------- +Getting Started +--------------- + +Let's start off by creating a file named ``mytrivia.yaml``. +Our trivia list will be named after the file, so in this case, +it will be called ``mytrivia``. + +------------ +Author Field +------------ + +We should first include an ``AUTHOR`` field, +to let the user know who wrote the questions. + +When the user starts the trivia, the author(s) will +be sent in the starting message (see below). + +.. image:: .resources/trivia/trivia_author.png + +The following should be placed at the top of your file, replacing "Red" +with your name: + +.. code-block:: yaml + + AUTHOR: Red + +If there are multiple authors, we can separate them with commas. + +.. code-block:: yaml + + AUTHOR: Red, Rojo, Rouge + +--------------------- +Questions and Answers +--------------------- + +Writing questions and answers is simple. Once you've finished your +``AUTHOR`` field, you can move on to your questions just below. + +Questions should consist of at least one answer, with other +possible answers included if necessary. You must put a colon at the end +of the question, for example: + +.. code-block:: yaml + + How many days are there in a regular year?: + +Answers will follow below, each separated by a line break and with a +hyphen at the start of the line. + +.. code-block:: yaml + + How many days are there in a regular year?: + - 365 + - three hundred and sixty five + +It's always nice to include alternative answers if a question needs it. +We can add as many valid answers as we'd like below this question. Answers +are **NOT** case sensitive, so you don't need to worry about adding the same +answer multiple times in different casings. + +There are multiple special characters in YAML, such as colons, hashtags, hyphens +and more. If these characters are included within our questions or answers, +you'll need to enclose the content with quotation marks. + +.. code-block:: yaml + + "Who is the #1 followed user on Twitter?": + +If we didn't have these quotation marks, the question would not render. + +.. code-block:: yaml + + Who is the #1 followed user on Twitter?: + +.. tip:: + + We can also include line breaks within our questions by using ``\n``, like + this for example: + + .. code-block:: yaml + + "My first line\nMy second line": + +As you've added more questions, your file should look something like this: + +.. code-block:: yaml + + AUTHOR: Red + How many days are there in a regular year?: + - 365 + - three hundred and sixty five + "Who is the #1 followed user on Twitter?": + - Barack Obama + - Obama + What is the only sea without any coasts?: + - Sargasso + - Sargasso Sea + Who won the Premier League in 2015?: + - Chelsea + - chelsea f.c. + How much money is a US Olympic gold medalist awarded?: + - $25,000 + - 25,000 + - 25k + - 25000 + - $25000 + +You can keep adding questions until you are satisfied, and then you can upload and +play your very own trivia! See :ref:`here ` for more details. + +Still stuck? Take a look at +`the core trivia lists `_ +for reference. diff --git a/docs/index.rst b/docs/index.rst index fc2371958..a5ff2f2f4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,6 +26,7 @@ Welcome to Red - Discord Bot's documentation! cog_customcom cog_permissions + guide_trivia_list_creation .. toctree:: :maxdepth: 2