From 9d4e34dace496d0a68ca4f83dffadb1f82e595d4 Mon Sep 17 00:00:00 2001 From: Andrei Date: Thu, 27 Apr 2017 10:19:22 -0700 Subject: [PATCH] More DOCS stuff --- .biblio.yaml | 8 +++ .gitignore | 10 ++- docs/BUILDING_A_BOT.md | 15 ----- docs/CLIENT.md | 39 ------------ docs/README.md | 4 +- docs/SUMMARY.md | 61 ++++++++++++++++++- docs/bot_tutorial/advanced.md | 0 docs/bot_tutorial/building_block_commands.md | 0 docs/bot_tutorial/building_block_listeners.md | 0 docs/bot_tutorial/first_steps.md | 53 ++++++++++++++++ docs/bot_tutorial/message_embeds.md | 0 docs/bot_tutorial/writing_a_plugin.md | 0 docs/{INSTALLATION.md => installation.md} | 0 13 files changed, 128 insertions(+), 62 deletions(-) create mode 100644 .biblio.yaml delete mode 100644 docs/BUILDING_A_BOT.md delete mode 100644 docs/CLIENT.md create mode 100644 docs/bot_tutorial/advanced.md create mode 100644 docs/bot_tutorial/building_block_commands.md create mode 100644 docs/bot_tutorial/building_block_listeners.md create mode 100644 docs/bot_tutorial/first_steps.md create mode 100644 docs/bot_tutorial/message_embeds.md create mode 100644 docs/bot_tutorial/writing_a_plugin.md rename docs/{INSTALLATION.md => installation.md} (100%) diff --git a/.biblio.yaml b/.biblio.yaml new file mode 100644 index 0000000..1571de5 --- /dev/null +++ b/.biblio.yaml @@ -0,0 +1,8 @@ +name: Disco + +rules: + disco/*.py: + parser: numpy + +outputs: + - {type: markdown, path: _build, title: 'Disco Documentation'} diff --git a/.gitignore b/.gitignore index 016ef0a..8b3cba2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,13 @@ build/ dist/ disco*.egg-info/ -docs/_build storage.db -_book/ -node_modules/ storage.json *.dca +.eggs/ + +# Documentation stuff +docs/api/ +docs/_build +_book/ +node_modules/ diff --git a/docs/BUILDING_A_BOT.md b/docs/BUILDING_A_BOT.md deleted file mode 100644 index 6099b8f..0000000 --- a/docs/BUILDING_A_BOT.md +++ /dev/null @@ -1,15 +0,0 @@ -# Building a Bot - -First up, its important to clarify what a bot describes in Disco-land. Disco has a built-in bot/plugin/command framework, which allows you to quickly and easily build fully functional bots. A bot defines a set of rules for parsing and handling commands, user and role permissions for those commands, and a set of plugins which will be loaded at runtime. - -## Your First Bot - -Disco has builtin support for building and running bots, which makes building your first bot extremely easy. - -``` -config.yaml -plugin_name/ - plugin_name.py -``` - -You can replace `plugin_name` with whatever makes the most since for your project \ No newline at end of file diff --git a/docs/CLIENT.md b/docs/CLIENT.md deleted file mode 100644 index 7649edc..0000000 --- a/docs/CLIENT.md +++ /dev/null @@ -1,39 +0,0 @@ -# Client - -Generally, almost all interactions through Disco will utilize some form of the Disco client. The client is an abstraction over the multiple transport and API protocols used to communicate with Discord, and it also includes utilities for tracking and caching real-time state. Most users will not want to construct an instance of the client themselves, but rather utilize one of Disco's helper facets (such as a Bot) that further wrap and abstract the client. - - -## API - -### ClientConfig - -Object used to configure the basic behavior and functionality of the client. - -#### Attributes - -| Field | Type | Description | Default | -|-------|------|-------------|---------| -| token | string | The Discord authentication token | `""` | -| shard\_id | integer | The shard ID for this instance | `0` | -| shard\_count | integer | The total number of shards | `1` | -| max\_reconnects | integer | The maxmium number of reconnects (not resumes) to attempt before giving up | `5` | -| manhole\_enable | boolean | Whether the manhole server is enabled | `False` | -| manhole\_bind | tuple(string, integer) | The bind information for the manhole server | `('127.0.0.1', 8484)` | - - -### Client - -Class representing the base abstraction point of Disco. - -#### Parameters - -| Name | Type | Description | -|------|------|-------------| -| config | `ClientConfig` | The configuration for this client instance | - -#### Attributes - -| Field | Type | Description | -|-------|------|-------------| -| config | `ClientConfig` | The configuration for this client instance | -| events | `holster.emitter.Emitter` | diff --git a/docs/README.md b/docs/README.md index 8bc948f..85b3184 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Disco -Disco is a simple, clean and extendable library for the [Discord API](https://dis.gd/docs). Disco is intended to be the easiest option for building both simple and complex API integrations, while also remaining an option for power-users looking to build large bots spanning thousands of servers. +Disco is a simple, clean and extendable library for the [Discord API](https://dis.gd/docs). Disco is built and aimed at developers looking to quickly start building bots that can be grown and extended to live on thousands of servers, and have immense functionality. To facilitate this, Disco provides a clean and simple interface which gets out of the way, but never sacrifices functionality. Disco is actively used by the staff at Discord to help us build and test Discord. ## Stability @@ -11,4 +11,4 @@ Disco is still a relatively young library, and as such it bears the "alpha" tag. * Expressive, Idiomatic, and Functional - the API interface stays out of our way, while giving you the required power * Performant and Efficient - allowing you to build bots that operate on many thousands of servers, without manual sharding * Modular and Extendable - take only the bits you need to build what you want, while being able to add or remove functionality by installing packages -* Python 2.x/3.x Support - build integrations with the version of Python you need to \ No newline at end of file +* Python 2.x/3.x Support - build integrations with the version of Python you need to diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4a1f4dc..3c1baec 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,8 +1,63 @@ # Summary * [Introduction](README.md) -* [Installation and Setup](INSTALLATION.md) -* [Building a Bot](BUILDING_A_BOT.md) +* [Installation and Setup](installation.md) +* [Bot Tutorial](bot_tutorial/intro.md) + * [Creating and Running a Bot](bot_tutorial/first_steps.md) + * [Writing a Plugin](bot_tutorial/writing_a_plugin.md) + * Building Blocks + * [Commands](bot_tutorial/building_block_commands.md) + * [Listeners](bot_tutorial/building_block_listeners.md) + * [Message Embeds](bot_tutorial/message_embeds.md) + * [Advanced](bot_tutorial/advanced.md) * API Docs - * [Client](api/disco_client.md) + * [disco.client](api/disco_client.md) + * [disco.state](api/disco_state.md) + * [disco.cli](api/disco_cli.md) + * Bot + * [disco.bot.bot](api/disco_bot_bot.md) + * [disco.bot.plugin](api/disco_bot_plugin.md) + * [disco.bot.command](api/disco_bot_command.md) + * [disco.bot.storage](api/disco_bot_storage.md) + * [disco.bot.parser](api/disco_bot_parser.md) + * API + * [disco.api.client](api/disco_api_client.md) + * [disco.api.http](api/disco_api_http.md) + * [disco.api.ratelimit](api/disco_api_ratelimit.md) + * Gateway + * [disco.gateway.client](api/disco_gateway_client.md) + * [disco.gateway.events](api/disco_gateway_events.md) + * [disco.gateway.packets](api/disco_gateway_packets.md) + * [disco.gateway.sharder](api/disco_gateway_sharder.md) + * [disco.gateway.ipc](api/disco_gateway_ipc.md) + * Types + * [disco.types.base](api/disco_types_base.md) + * [disco.types.channel](api/disco_types_channel.md) + * [disco.types.guild](api/disco_types_guild.md) + * [disco.types.invite](api/disco_types_invite.md) + * [disco.types.message](api/disco_types_message.md) + * [disco.types.permissions](api/disco_types_permissions.md) + * [disco.types.user](api/disco_types_user.md) + * [disco.types.voice](api/disco_types_voice.md) + * [disco.types.webhook](api/disco_types_webhook.md) + * Util + * [disco.util](api/disco_util.md) + * [disco.util.backdoor](api/disco_util_backdoor.md) + * [disco.util.chains](api/disco_util_chains.md) + * [disco.util.config](api/disco_util_config.md) + * [disco.util.functional](api/disco_util_functional.md) + * [disco.util.hashmap](api/disco_util_hashmap.md) + * [disco.util.limiter](api/disco_util_limiter.md) + * [disco.util.logging](api/disco_util_logging.md) + * [disco.util.sanitize](api/disco_util_sanitize.md) + * [disco.util.snowflake](api/disco_util_snowflake.md) + * [disco.util.token](api/disco_util_token.md) + * [disco.util.websocket](api/disco_util_websocket.md) + * Voice + * [disco.voice.client](api/disco_voice_client.md) + * [disco.voice.opus](api/disco_voice_opus.md) + * [disco.voice.packets](api/disco_voice_packets.md) + * [disco.voice.playable](api/disco_voice_playable.md) + * [disco.voice.player](api/disco_voice_player.md) + diff --git a/docs/bot_tutorial/advanced.md b/docs/bot_tutorial/advanced.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/bot_tutorial/building_block_commands.md b/docs/bot_tutorial/building_block_commands.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/bot_tutorial/building_block_listeners.md b/docs/bot_tutorial/building_block_listeners.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/bot_tutorial/first_steps.md b/docs/bot_tutorial/first_steps.md new file mode 100644 index 0000000..f6961ac --- /dev/null +++ b/docs/bot_tutorial/first_steps.md @@ -0,0 +1,53 @@ +# Bot Tutorial + +Disco provides a built-in set of tools for building and running Discord bots which can be used to quickly and easily create integrations. Within this tutorial you'll be shown how to install Disco, write plugins, and run bots. This tutorial assumes you've already followed the [Installation Steps](../installation.md). + +## Creating a Bot + +The first step to creating bots is to actually register them on Discord itself. To do this, you'll need to be logged into your Discord account on the browser and then navigate to [My Apps](https://discordapp.com/developers/applications/me). Here you'll have the option to create a new application, and once created you can add a bot user (by clicking "Create a Bot User") to your application. Finally, you'll want to keep track of the bot user token which can be shown by clicking the "click to reveal" link next to the token field. + +Once you have a Discord bot account, you can then setup your workspace. For now we'll just need a folder (perhaps called `disco-tutorial`) with a few files in it: + +``` +disco-tutorial/ + config.yaml + plugins/ + tutorial.py +``` + + +Within the config file, paste the following template configuration and modify the token key to contain the token you obtained above: + +```yaml +token: 'MY_BOT_TOKEN_HERE' + +bot: + plugins: + - plugins.tutorial +``` + +Now, within the python file (`tutorial.py`), lets write some code: + + +```python +from disco.bot import Plugin + + +class TutorialPlugin(Plugin): + @Plugin.command('ping') + def command_ping(self, event): + event.msg.reply('Pong!') +``` + +And finally, we're ready to start and test the bot. We can do this by executing the following command from within our project directory: + + +```sh +python -m disco.cli --config config.yaml +``` + +If all is successful, you can then test your bot by mentioning it with the command, like so: + +``` +@tutorial#1234 ping +``` diff --git a/docs/bot_tutorial/message_embeds.md b/docs/bot_tutorial/message_embeds.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/bot_tutorial/writing_a_plugin.md b/docs/bot_tutorial/writing_a_plugin.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/INSTALLATION.md b/docs/installation.md similarity index 100% rename from docs/INSTALLATION.md rename to docs/installation.md