Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add guides to docs #1522

Draft
wants to merge 4 commits into
base: master
Choose a base branch
from
Draft

Conversation

hypergonial
Copy link
Contributor

@hypergonial hypergonial commented Feb 25, 2023

Summary

Add a "Guides" section to the documentation where users new to the library are introduced to core concepts and features of the library.

The guides should be written with the assumption that the user is already familiar with Python, but not the Discord API or hikari.

Progress

  • Events
  • Intents
  • Obtaining data from the API (cache & rest)
  • Interactions
  • Extension libraries

If you feel like more topics should be covered, feel free to leave a comment below or create a PR to this branch!

@hypergonial hypergonial changed the title Add event guides Add guides to docs Feb 25, 2023
Copy link
Contributor

@Lunarmagpie Lunarmagpie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some small ideas for improvements

docs/guides/events/advanced.md Outdated Show resolved Hide resolved
docs/guides/events/advanced.md Outdated Show resolved Hide resolved
Comment on lines +27 to +33
You may also put the event's type in the decorator instead of a type annotation:

```py
@bot.listen(hikari.MessageCreateEvent)
async def message_listener(event) -> None:
print(f"I have received a message from {event.author} in {event.channel_id}!")
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although this is possible, does the guide need to show this?

Suggested change
You may also put the event's type in the decorator instead of a type annotation:
```py
@bot.listen(hikari.MessageCreateEvent)
async def message_listener(event) -> None:
print(f"I have received a message from {event.author} in {event.channel_id}!")
```
You may also put the event's type in the decorator instead of a type annotation:
```py
@bot.listen(hikari.MessageCreateEvent)
async def message_listener(event) -> None:
print(f"I have received a message from {event.author} in {event.channel_id}!")

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is important to note in scenarios where type annotation usage may not be feasible or possible, yes.

docs/guides/events/basics.md Outdated Show resolved Hide resolved
@davfsa davfsa added documentation Improvements or additions to documentation skip-fragment-check Skip fragment checks for this PR as it doesnt need one labels Feb 25, 2023
docs/guides/events/basics.md Outdated Show resolved Hide resolved
docs/guides/events/basics.md Outdated Show resolved Hide resolved
docs/guides/events/basics.md Outdated Show resolved Hide resolved
docs/guides/events/basics.md Outdated Show resolved Hide resolved
async def message_listener(event: hikari.MessageCreateEvent) -> None:
print(f"I have received a message from {event.author} in {event.channel_id}!")

# -- Snip --
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are the # -- Snip --'s necessary here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say yes.

docs/guides/data.md Outdated Show resolved Hide resolved
docs/guides/data.md Outdated Show resolved Hide resolved
docs/guides/data.md Outdated Show resolved Hide resolved
docs/guides/data.md Outdated Show resolved Hide resolved
docs/guides/data.md Outdated Show resolved Hide resolved
Co-authored-by: Nova <[email protected]>
Signed-off-by: Hyper <[email protected]>
@davfsa
Copy link
Member

davfsa commented Jan 21, 2024

This can most probably be merged into #1810

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation skip-fragment-check Skip fragment checks for this PR as it doesnt need one
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants