Open Rapptz opened 2 years ago
How about implementing #5851.
A possible Deployment guide could cover:
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.
Djs has guide on clustering, So it would be nice to have one here as well
What about adding how to setup a proper working enviroment (including typechecking) to utilise the lib types?
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.
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)
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.
Guide on OAuth (like d.js guide)
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?
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.
@ImNimboss That's more of a suitable thing for FAQ and it's already there.
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 ofasyncio.sleep
,praw
instead ofasyncpraw
, 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.
Ah, alright
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.
~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.
A guide to working with / command should be included in the documentation @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:
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 thedocs/guide
branch rather than themaster
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 thedocs/
directory. So e.g.intro.rst
means the file should be located indocs/guide/intro.rst
.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.