Merge pull request #4 from AW1534/dev

restructured docs
AW1534 · Feb 5, 2022 · 0f5ef63 · 0f5ef63
2 parents 8cf5ecf + 10d01e1
commit 0f5ef63
Show file tree

Hide file tree

Showing 6 changed files with 137 additions and 120 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 [![Documentation Status](https://readthedocs.org/projects/cry-vs-py/badge/?version=latest)](https://cry-vs-py.readthedocs.io/en/latest/?badge=latest) [![](https://img.shields.io/pypi/v/cry-vs.py)](https://pypi.org/project/cry-vs.py/) ![](https://img.shields.io/github/repo-size/AW1534/cry-vs.py)
 # cry-vs.py
-Just a simple wrapper to assist you with the simple crypto-versus API.
+*Just a simple wrapper to assist you with the simple crypto-versus API.*
 
 *docs [here](https://cry-vs-py.readthedocs.io/)*
 

diff --git a/docs/_build/html/_static/js/script.js → docs/_static/js/script.js b/docs/_build/html/_static/js/script.js → docs/_static/js/script.js
@@ -2,16 +2,23 @@
 
 
 // override ctrl + f command
-document.addEventListener('keydown', function(e) {
+document.addEventListener("keydown", function(e) {
     if (e.keyCode === 70 && e.ctrlKey) {
         e.preventDefault(); // cancel default behavior
         let navigation = document.getElementById("__navigation") // get the navigation element
 
         if (navigation.checked) { // if the navigation is not visible, show it, wait for a small delay and focus the search input
             document.getElementById("__navigation").checked = false;
-            setTimeout(() => document.getElementById('search-input').focus(), 10);
+            setTimeout(() => document.getElementById('search-input').focus(), 50);
+
+            document.addEventListener("keydown", function(e) {
+                if (e.keyCode === 27) { // if the escape key is pressed, hide the navigation
+                    document.getElementById("__navigation").checked = true;
+                }
+            },  { once: true }); // only listen to this event once since it will be redundant after the first time
+
         } else { // if the navigation is visible, just focus the search input
-            document.getElementById('search-input').focus()
+            document.getElementById('search-input').focus();
         }
     }
-});
+})
diff --git a/docs/conf.py b/docs/conf.py
@@ -13,6 +13,9 @@
 
 ogp_site_url = "http://cry-vs-py.readthedocs.io/"
 ogp_type = "article"
+ogp_custom_meta_tags = [
+    '<meta property="og:ignore_canonical" content="true" />',
+]
 
 extensions = [
     "myst_parser",

diff --git a/docs/index.md b/docs/index.md
@@ -1,86 +1,40 @@
 # cry-vs
-An official API wrapper for [Crypto_Versus](https://github.com/ProtagonistsWasTaken/crypto_versus)
+*An official API wrapper for [Crypto_Versus](https://github.com/ProtagonistsWasTaken/crypto_versus)*
 
-## Installation
-Installation is simple. just run `$ python -m pip install cry_vs.py` in your terminal.
 
-## Usage
-```{note} 
-This package is used in a way similar to [discord.py](https://pypi.org/project/discord.py/). if you know how to use discord.py, the following steps should be a cakewalk.
-```
+````{panels}
+Modern ✨
+^^^
+cry-vs.py is a modern library, with support for `async` and `await`.
 
 ---
-### Initialization & logger setup
-First set up the logging module. this is not necessary because cry_vs will try to set up the logging module for you, but is highly recommended.
-```python
-import logging, sys
-logging.basicConfig(encoding="utf-8", stream=sys.stdout, level=logging.INFO)
-```
-
-Next, import cry_vs's client class.
-
-```python
-from cry_vs.client import Client
-```
-
-Once you have done that, you can create a client.
-
-```python
-cry = Client()
-```
-
-while there are no required arguments, you can also pass in the other arguments.
-
-| **Name**           | **Type** | **Default value**      | **Description**                                                             |
-|--------------------|----------|------------------------|-----------------------------------------------------------------------------|
-| **host**           | string   | "cry-vs.herokuapp.com" | The url of the server you want to connect to.                               |
-| **port**           | int      | 80                     | The port that the socket should listen to.                                  |
-| **allow_unsecure** | bool     | False                  | Whether to allow unsecure connections.                                      |
-| **keep_alive**     | bool     | True                   | Whether to keep the client validated by automatically refreshing the token. |
 
+Full API coverage 🔨
+^^^
+built by a maintainer of [Crypto_Versus](https://github.com/ProtagonistsWasTaken/crypto_versus) itself, cry-vs.py supports the full API, implementing beta features as they are released.
 
 ---
-### events
-Now that you have a client, you can start listening to events. to do so, just make a function with the `@cry.listen` decorator.
-
-for example, if you want to listen to the `on_ready` event, you would do the following:
-```python
-@cry.listen
-async def on_ready():
-    print("on_ready has been called")
-```
-
-you can add as many events as you want, and they depend on the name. (function must be asynchronous)
 
-| **Name**             | **Description**                                                                    |
-|----------------------|------------------------------------------------------------------------------------|
-| **any_event**        | Fired when any event is called                                                     |                                                                                    |
-| **on_ready**         | Fired when the event emitter is initialized (right after the client has logged in) |
-| **on_token_refresh** | Fired after the token has been refreshed                                           |
+Easy to use 📦
+^^^
+cry-vs.py is a simple, easy to use library, with a simple API.
+ 
+*[here](https://github.com/ProtagonistsWasTaken/crypto_versus/example) is an example of an application using every feature, in just one short file*
 
 ---
-### finalize
-finally, you can call `cry.login()` to start the client.
 
-````{tabbed} API Key
-```python
-cry.login("key")
-```
-````
+Open source 🌐
+^^^
+Nothing spooky, nothing scary, cry-vs.py is open source, and licensed under a very open [license](https://github.com/ProtagonistsWasTaken/crypto_versus/LICENSE).
 
-````{tabbed} Username and Password
-```python
-cry.login("username", "password")
-```
 ````
-```{warning}
-this will start the event loop, and will not return until the client is closed. any logic that needs to be done after this function should be done in the `on_ready` event.
-```
 
 ```{toctree}
 :hidden:
-reference.md
+intro.md
 ```
 
-
-<!-- footer gets added here for pypi version in setup.py-->
+```{toctree}
+:hidden:
+reference.md
+```
diff --git a/docs/intro.md b/docs/intro.md
@@ -0,0 +1,84 @@
+# Starter Guide
+*How to get started with cry-vs.py*
+
+This is a short guide to help you get a project up and running.
+you should then go to the [API reference](/reference.md) to extend the functionality of your project.
+
+## Installation
+Installation is simple. just run `$ python -m pip install cry_vs.py` in your terminal.
+
+## Usage
+```{note} 
+This package is used in a way similar to [discord.py](https://pypi.org/project/discord.py/). if you are familiar with it, the following steps should be a cakewalk.
+```
+
+---
+### Initialization & logger setup
+First set up the logging module. this is not necessary because cry_vs will try to set up the logging module for you, but is highly recommended.
+```python
+import logging, sys
+logging.basicConfig(encoding="utf-8", stream=sys.stdout, level=logging.INFO)
+```
+
+Next, import cry_vs's client class.
+
+```python
+from cry_vs.client import Client
+```
+
+Once you have done that, you can create a client.
+
+```python
+cry = Client()
+```
+
+while there are no required arguments, you can also pass in the other arguments.
+
+| **Name**           | **Type** | **Default value**      | **Description**                                                             |
+|--------------------|----------|------------------------|-----------------------------------------------------------------------------|
+| **host**           | string   | "cry-vs.herokuapp.com" | The url of the server you want to connect to.                               |
+| **port**           | int      | 80                     | The port that the socket should listen to.                                  |
+| **allow_unsecure** | bool     | False                  | Whether to allow unsecure connections.                                      |
+| **keep_alive**     | bool     | True                   | Whether to keep the client validated by automatically refreshing the token. |
+
+
+---
+### events
+Now that you have a client, you can start listening to events. to do so, just make a function with the `@cry.listen` decorator.
+
+for example, if you want to listen to the `on_ready` event, you would do the following:
+```python
+@cry.listen
+async def on_ready():
+    print("on_ready has been called")
+```
+
+you can add as many events as you want, and they depend on the name. (function must be asynchronous)
+
+| **Name**             | **Description**                                                                    |
+|----------------------|------------------------------------------------------------------------------------|
+| **any_event**        | Fired when any event is called                                                     |                                                                                    |
+| **on_ready**         | Fired when the event emitter is initialized (right after the client has logged in) |
+| **on_token_refresh** | Fired after the token has been refreshed                                           |
+
+---
+### finalize
+finally, you can call `cry.login()` to start the client.
+
+````{tabbed} API Key
+```python
+cry.login("key")
+```
+````
+
+````{tabbed} Username and Password
+```python
+cry.login("username", "password")
+```
+````
+```{warning}
+this will start the event loop, and will not return until the client is closed. any logic that needs to be done after this function should be done in the `on_ready` event.
+```
+
+
+<!-- footer gets added here for pypi version in setup.py-->
diff --git a/docs/reference.md b/docs/reference.md
@@ -1,67 +1,40 @@
 # API reference
-An official API wrapper for [Crypto_Versus](https://github.com/ProtagonistsWasTaken/crypto_versus)
+*An official API wrapper for [Crypto_Versus](https://github.com/ProtagonistsWasTaken/crypto_versus)*
 
-## Installation
-Installation is simple. just run `$ python -m pip install cry_vs.py` in your terminal.
+*this section is under construction, and isn't very good yet*
 
-## Usage
-```{note} 
-This package is used in a way similar to [discord.py](https://pypi.org/project/discord.py/). if you know how to use discord.py, the following steps should be a cakewalk.
-```
-
----
-### Initialization & logger setup
-First set up the logging module. this is not necessary because cry_vs will try to set up the logging module for you, but is highly recommended.
-```python
-import logging, sys
-logging.basicConfig(encoding="utf-8", stream=sys.stdout, level=logging.INFO)
-```
-
-Next, import cry_vs's client class.
-
-```python
-from cry_vs.client import Client
-```
-
-Once you have done that, you can create a client.
-
-```python
-cry = Client()
-```
-
-while there are no required arguments, you can also pass in the other arguments.
+## Client
 
+### Constructor parameters
 | **Name**           | **Type** | **Default value**      | **Description**                                                             |
 |--------------------|----------|------------------------|-----------------------------------------------------------------------------|
 | **host**           | string   | "cry-vs.herokuapp.com" | The url of the server you want to connect to.                               |
 | **port**           | int      | 80                     | The port that the socket should listen to.                                  |
 | **allow_unsecure** | bool     | False                  | Whether to allow unsecure connections.                                      |
 | **keep_alive**     | bool     | True                   | Whether to keep the client validated by automatically refreshing the token. |
 
+### Exposed methods
 
----
-### events
-Now that you have a client, you can start listening to events. to do so, just make a function with the `@cry.listen` decorator.
+| **Name**               | **Parameters**                          | **Returns**                 | **Login required** | **Description**                                                                                                                                  |
+|------------------------|-----------------------------------------|-----------------------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Client.listen**      | N/A                                     | N/A                         | No                 | Should be used as a decorator. registers the function as an [event handler](#events).                                                            |
+| **Client.login**       | `username`, `password` *or* `API token` | N/A                         | No                 | Authenticates the client. this will also start the event loop so any code that needs to be done before this should be done in the on_ready event |
+| **Client.game.action** | N/A                                     | JSON (HTTP response object) | Yes                | call the `/api/v0/dostuff` endpoint. that endpoint is temporary and so is this method.                                                           |
 
-for example, if you want to listen to the `on_ready` event, you would do the following:
-```python
-@cry.listen
-async def on_ready():
-    print("on_ready has been called")
-```
+### Exposed variables
+*coming soon™*
 
-you can add as many events as you want, and they depend on the name. (function must be asynchronous)
 
+
+## events
+to create an event handler, just use the `@Client.listen` decorator. The client will automatically call the handler based on the function name.
 | **Name**             | **Description**                                                                    |
 |----------------------|------------------------------------------------------------------------------------|
 | **any_event**        | Fired when any event is called                                                     |                                                                                    |
 | **on_ready**         | Fired when the event emitter is initialized (right after the client has logged in) |
 | **on_token_refresh** | Fired after the token has been refreshed                                           |
 
----
-### finalize
-finally, you can call `cry.login()` to start the client.
-
+## login parameters
 ````{tabbed} API Key
 ```python
 cry.login("key")
@@ -72,8 +45,4 @@ cry.login("key")
 ```python
 cry.login("username", "password")
 ```
-````
-```{warning}
-this will start the event loop, and will not return until the client is closed. any logic that needs to be done after this function should be done in the `on_ready` event.
-```
-
+````