The discord.py Guide

[Rapptz]

Introduction

People have often wanted better documentation and a great desire of mine has always been to have a proper guide set up so we could improve the on-boarding experience for newer developers using discord.py. The following are topics that I think would be well fit for an actual guide in using discord.py.

Please note that this isn't a complete list, but it's just something more concrete for people to work on and contribute than just a nebulous "improve the docs" statement.

Inspiration:

• django
• discord.js's guide
• Click

etc.

Project Management and Contributing

This is a pretty big undertaking for me to do all the reviews on my own since there are other parts of the library that need attention as well. Therefore, I've assigned two people to do reviews in my stead and once one of them sign off on a PR, I'll give it one final glance before ultimately merging it.

The project managers for this documentation reform are:

• @Gorialis
• @EvieePy

Contributing

The first thing to do, is to join the official server and ask me or any of the project managers for the Documentation role. This allows you to gain access to #docs, which is where live discussion takes place on how the guide should be worded and other contribution questions.

After you've discussed this in the Discord server, open a PR and give it "Guide" in the title somewhere when you've written the guide's contents. It'll be tagged with the guide label to let the project managers know what to look at. The pull request should target the docs/guide branch rather than the master branch. Things in the high level overview with a checkbox have already been assigned to someone else!

Note that a PR might be closed if either it is done without consulting in the Discord server first, or it is not sufficiently high quality per my decision or the decision of the project managers. Please remember we all do this on our own free time and we have limited bandwidth but our ultimate goal remains the same: improving the documentation for the sake of others.

Target Audience

The target audience of the guide is for intermediate Python programmers. Basically, people who understand the basics of Python such as classes, functions, and decorators but may not be familiar with asynchronous programming or asyncio. The point of this guide is not to teach users how to write Python code.

The High Level

Ideally we'd rearrange the entire "Getting Started" and FAQ sections into a new page called a guide with a giant TOC to the individual subpages. If Sphinx does not allow for these nested-page TOC then work should be done to allow for that, however the content comes first. At some point work will be done in the extension in order to facilitate the complicated table of contents structure necessary for the guide, if this becomes at all needed.

The Guide

The following is a table of contents for the eventual guide page. These all belong into a root guide/ directory inside the docs/ directory. So e.g. intro.rst means the file should be located in docs/guide/intro.rst.

• [x] Introduction (intro.rst) (#7500)
  • Installing
  • Virtual Environments
  • [x] Redesign the "Basic Concepts" part.
  • Making an Application
• [x] Getting Started (quickstart.rst) (#7500)
  • This one will walk them through creating a basic bot using the command extension. It should also contain a link to how to get started using application commands if they want that too.
• [ ] Slash Commands and Interactions (interactions/index.rst)
  • [x] Slash Commands (interactions/slash_commands.rst)
    • This one will go over everything involving how to make or use slash commands.
    • This includes concepts like groups and stuff. This page might end up big!
  • [x] Context Menu Commands (interactions/context_menus.rst)
    • This is the same but for context menus.
  • [x] Views (interactions/views.rst) (#7507)
    • Everything involving views, buttons, selects, etc.
  • [x] Modals (interactions/modals.rst) (#7507)
    • Everything involving modals
• [x] Popular Topics (topics/index.rst)
  • [x] Asynchronous Programming (topics/asyncio.rst) (#7718)
  • [x] Embeds (topics/embeds.rst) (#7498)
    • This would have everything about embeds, e.g. uploading an image to an embed using attachment:// etc.
  • [x] Threads (topics/threads.rst) (#7496)
  • [x] Reactions (topics/reactions.rst) (#7495)
  • [x] Permissions (topics/permissions.rst) (#7497)
    • This includes things like overwrites
  • [x] Intents (topics/intents.rst)
    • Basically move the pre-existing intent guide here.
  • [ ] Partial Models (topics/partials.rst)
    • Everything about partial models.
  • [x] Audit Logs (topics/audit_logs.rst) (#7571)
  • [x] Webhooks (topics/webhooks.rst) (#7663)
  • [x] Waiting for Events or Input (topics/wait_for.rst) (#7709)
    • Talks about how to use wait_for with your bot
  • [x] Markdown (topics/markdown.rst) (#7720)
    • Quick guide on markdown.
    • Probably also goes over discord specific implementations
    • Maybe escaping markdown too.
  • [ ] Voice (topics/voice.rst)
    • Discuss FFmpeg / Youtube-DL / Lavalink?
• [x] Sharding (sharding/index.rst) (#7499)
  • AutoShardedClient
  • This could use some fleshing out...
• [x] Databases (databases.rst)
  • SQLite
  • PostgreSQL
  • JSON
  • MongoDB

Closing Thoughts

If there is anything needed to discuss this hypothetical TOC, please comment below. I also may have missed a lot of things so any suggestions would be more than welcome and doesn't have to be restricted to this list. I just wanted to make a list of things so people would know a general direction in case they want to start writing or contributing but don't know what to do.

[Luc1412]

How about implementing #5851.

A possible Deployment guide could cover:

• Free Hosting and why not to use it
• Systemd
• Docker
• possible other great deployment methods

[EvieePy]

I'm not a fan of mentioning anything related to free hosting, as it will likely be too opinionated and a breeding ground for arguments. But that's just my opinion.

It would be nice to see a guide on how to deploy to various operating systems/process managers and the benefits of using them.

[Tari-dev]

Djs has guide on clustering, So it would be nice to have one here as well

[r-priyam]

What about adding how to setup a proper working enviroment (including typechecking) to utilise the lib types?

[AbstractUmbra]

What about adding how to setup a proper working enviroment (including typechecking) to utilise the lib types?

I believe most of what's needed here will be covered within the getting started guide that is underway from @XuaTheGrate. The only addition would be installing pyright and using it's command args correctly. Pylance (as part of Visual Studio Code) should work also it utilises pyright too.

The only caveat is that dpy is currently only type checks correctly with pyright, others such Mypy and the JetBrains proprietary one will not work here.

[alistair-broomhead]

RE Hosting, I can see that a potentially useful guide might be something like "Here's everything you need to do to set up your bot on a fresh Raspbian install", given how that provides a cheap way to get started, and the skills to expand it out to other hosting?

(I run my own bots off a Raspberry Pi 2 B I found gathering dust at the back of a cupboard, and for small projects it's great)

[AbstractUmbra]

RE Hosting, I can see that a potentially useful guide might be something like "Here's everything you need to do to set up your bot on a fresh Raspbian install", given how that provides a cheap way to get started, and the skills to expand it out to other hosting?

(I run my own bots off a Raspberry Pi 2 B I found gathering dust at the back of a cupboard, and for small projects it's great)

This is on our collective mental checklist. This does mostly fall under generic "linux based" setups, so it will get covered. If you can think of other suggestions then feel free to hit us up on the discord server.

[GoogolGenius]

Guide on OAuth (like d.js guide)

[AbstractUmbra]

Guide on OAuth (like d.js guide)

discord.py has 0 interactions with OAuth so I don't believe this is something we need to consider?

[ImNimboss]

Perhaps a section on looking for async versions of external libraries/tools, if necessary

I have seen a lot of people use, for example, time.sleep instead of asyncio.sleep, praw instead of asyncpraw, etc. Depending on the tool, this could have really bad consequences for the bot.

[izxxr]

@ImNimboss That's more of a suitable thing for FAQ and it's already there.

[AbstractUmbra]

Perhaps a section on looking for async versions of external libraries/tools, if necessary

I have seen a lot of people use, for example, time.sleep instead of asyncio.sleep, praw instead of asyncpraw, etc. Depending on the tool, this could have really bad consequences for the bot.

I believe this has been covered at a higher level in the asyncio guide that was done already.

[ImNimboss]

Ah, alright

[alkatar21]

Maybe you could explain things like discord.abc.Snowflake or discord.Object and their uses, which at least to me were not immediately clear why they exist and when to use them.

This is not currently being addressed, unless I missed it.

[RobertCraigie]

~What is the idea for the databases part? Is there going to be a guide for just one database driver / ORM or should there be guides for multiple different database drivers / ORMs?~

~If there's only going to be guides for a singular database driver / ORM then I'd like to make the case for https://github.com/RobertCraigie/prisma-client-py.~

~Here's an example of how Prisma can be used with discord.py. It should be noted that I wrote that example on discord.py v1.7 and to conform to strict type checking. A more user friendly example would only target basic type checking.~

~Otherwise if there are going to be guides for many different ORMs then I would be more than happy to contribute a guide for Prisma :)~

Sorry about that, I didn't fully appreciate how my comment would come across.

[shahriaarrr]

A guide to working with / command should be included in the documentation @Rapptz