The discord.py Guide

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:

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:

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.

Introduction (intro.rst) (#7500)
- Installing
- Virtual Environments
- Redesign the “Basic Concepts” part.
- Making an Application
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)
- 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!
- Context Menu Commands (interactions/context_menus.rst)
  - This is the same but for context menus.
- Views (interactions/views.rst) (#7507)
  - Everything involving views, buttons, selects, etc.
- Modals (interactions/modals.rst) (#7507)
  - Everything involving modals
Popular Topics (topics/index.rst)
- Asynchronous Programming (topics/asyncio.rst) (#7718)
- Embeds (topics/embeds.rst) (#7498)
  - This would have everything about embeds, e.g. uploading an image to an embed using attachment:// etc.
- Threads (topics/threads.rst) (#7496)
- Reactions (topics/reactions.rst) (#7495)
- Permissions (topics/permissions.rst) (#7497)
  - This includes things like overwrites
- Intents (topics/intents.rst)
  - Basically move the pre-existing intent guide here.
- Partial Models (topics/partials.rst)
  - Everything about partial models.
- Audit Logs (topics/audit_logs.rst) (#7571)
- Webhooks (topics/webhooks.rst) (#7663)
- Waiting for Events or Input (topics/wait_for.rst) (#7709)
  - Talks about how to use wait_for with your bot
- 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?
Sharding (sharding/index.rst) (#7499)
- AutoShardedClient
- This could use some fleshing out…
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.