Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@EvieePy
EvieePy committed Mar 18, 2024
1 parent 377fc5a commit 5a4be9b
Show file tree
Hide file tree
Showing 5 changed files with 239 additions and 95 deletions.
128 changes: 128 additions & 0 deletions docs/getting-started/installing.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Installing TwitchIO

**TwitchIO 3 currently supports the following [Python](https://www.python.org/downloads/) versions:**


| Python Version | Status | Notes |
| ----------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **`<= 3.9`** | :fontawesome-solid-triangle-exclamation:{ .icon-warning .pythonista-tag title="Unsupported"} | Unsupported |
| **`3.10, 3.11, 3.12`** | :fontawesome-solid-check:{ .icon-check .pythonista-tag title="Supported" } | Supported |
| **`3.13`** | :fontawesome-solid-question:{ .icon-unknown .pythonista-tag title="Unknown" } | Unknown |


## Virtual Environments

TwitchIO recommends the use of Virtual Environments (venvs).

You can read more about [Virtual Environments here.](https://realpython.com/python-virtual-environments-a-primer/)
Below are some simple commands to help you get started with a **venv** and TwitchIO.

=== "Windows"

``` shell
# Change into your projects root directory or open a terminal there...
cd path/to/project

# Create the virtual environment...
# Replace 3.10 with the Python version you want to use...
# You can check what Python versions you have installed with:
# py -0
py -3.10 -m venv venv

# Activate your venv...
# Everytime you want to use your venv in a new terminal you should run this command...
# You will know your venv is activated if you see the (venv) prefix in your terminal...
venv/Scripts/Activate

# Install your packages...
pip install -U twitchio

# You can use your venv python while it's activated simply by running py
# E.g. py main.py
# E.g. py --version
py main.py

# You can deactivate your venv in this terminal with
deactivate

# REMEMBER!
# You have to re-activate your venv whenever it is deactivated to use for it for you project...
# You will know your venv is activated by looking for the (venv) prefix in your terminal
```


=== "Linux & MacOS"

``` shell
# Change into your projects root directory or open a terminal there...
cd path/to/project

# Create the virtual environment...
# Replace 3.10 with the Python version you want to use...
python3.10 -m venv venv

# Activate your venv...
# Everytime you want to use your venv in a new terminal you should run this command...
# You will know your venv is activated if you see the (venv) prefix in your terminal...
source venv/bin/activate

# Install your packages...
pip install -U twitchio

# You can use your venv python while it's activated simply by running python
# E.g. python main.py
# E.g. python --version
python main.py

# You can deactivate your venv in this terminal with
deactivate

# REMEMBER!
# You have to re-activate your venv whenever it is deactivated to use for it for you project...
# You will know your venv is activated by looking for the (venv) prefix in your terminal
```


## Extra and Optional Dependencies

To use certain optional features of TwitchIO you will have to install the required packages needed to run them.

The following commands can be used to install TwitchIO with optional features:

**To use the StarletteAdapter**:
```shell
pip install -U twitchio[starlette]
```

**For development purposes**:
```shell
pip install -U twitchio[dev]
```

**For documentation puposes**:
```shell
pip install -U twitchio[docs]
```


## Custom Index

Using TwitchIO with `Python >= 3.12` may require the use of a custom pip index.

The index allows pip to fetch pre-built wheels for some dependencies that may require build-tools for C/C++ due to not having released their own wheels for recent versions of Python.

Usually with time, dependencies will eventually release wheels for new Python releases.

For convenience we provide an index thanks to [Abstract Umbra](https://github.com/AbstractUmbra)

**To install with prebuilt wheels:**
``` shell
pip install -U twitchio --extra-index-url https://pip.pythonista.gg

```

## Installation Issues
Make sure you have the latest version of Python installed, or if you prefer, a Python version of 3.10 or greater.

If you have any other issues feel free to search for duplicates and then create a new issue on [GitHub](https://github.com/PythonistaGuild/twitchio) with as much detail as possible. Including providing the output of pip, your OS details and Python version.

5 changes: 3 additions & 2 deletions docs/requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
mkdocs-material
-i https://pypi.pythonista.gg/simple
griffe
mkdocstrings-python
mkdocstrings
mkdocs-material
68 changes: 66 additions & 2 deletions docs/stylesheets/extra.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
--md-typeset-color: #C9C9D1;
--md-default-bg-color: #15151C;
--md-footer-bg-color: #262633;
--pythonista-accent-color: #353557;

--md-code-fg-color: #efefff;
--md-code-bg-color: #23232e;
Expand All @@ -26,6 +27,10 @@
--md-admonition-fg-color: #efefff;
--md-typeset-table-color: rgb(201, 201, 209, .2);

.md-header {
background-color: var(--pythonista-accent-color);
}

.pythonista-tag {
background: var(--md-primary-fg-color);
padding: 0.5rem;
Expand Down Expand Up @@ -124,10 +129,26 @@
--md-code-hl-generic-color: #F5C2DA;
--md-code-hl-variable-color: #F5C2DA;

code {
background-color: var(--md-code-bg-color);
}

.doc-contents {
padding-left: 1rem;
}

.doc-object {
margin-left: -1rem;
}

.highlight span.filename {
background-color: #1D1D26;
}

.highlight {
background-color: #1D1D26;
}

.md-typeset {
font-size: 0.65rem;
}
Expand All @@ -143,14 +164,34 @@

.doc-label-async > code {
color: #F7BA00;
background-color: rgb(247, 186, 0, 0.05);
font-size: 1.05em;
font-weight: bold;
background-color: transparent;
}

.doc-symbol {
filter: opacity(0.8);
background-color: transparent;
}

.doc-label {
background-color: transparent;
}

.doc-heading {
font-size: 0.7rem;
font-weight: 400;
background-color: #1D1D26;
padding: 0.1rem;
}

.doc-symbol-attribute::after {
content: "attr";
}

.doc-label-writable > code {
color: #73D673;
background-color: rgb(115, 214, 115, 0.05);
background-color: transparent;
}

.doc-object {
Expand All @@ -168,4 +209,27 @@
display: block;
}

.inactiveLink {
pointer-events: none;
cursor: default;
color: var(--md-typeset-color);
}

.doc-label-property {
display: none;
}
}

::-webkit-scrollbar {
width: 0.3rem;
}

::-webkit-scrollbar-track {
background: var(--md-primary-fg-color);
border-radius: 0.05rem;
}

::-webkit-scrollbar-thumb {
background-color: var(--pythonista-accent-color);
border-radius: 0.05rem;
}
111 changes: 21 additions & 90 deletions docs/templates/python/material/docstring/attributes.html
View file
Original file line number Diff line number Diff line change
@@ -1,90 +1,21 @@
{{ log.debug("Rendering attributes section") }}

{% import "language.html" as lang with context %}

{% if config.docstring_section_style == "table" %}
{% block table_style %}
<p><strong>{{ section.title or lang.t("Attributes:") }}</strong></p>
<table>
<thead>
<tr>
<th>{{ lang.t("Name") }}</th>
<th>{{ lang.t("Type") }}</th>
<th>{{ lang.t("Description") }}</th>
</tr>
</thead>
<tbody>
{% for attribute in section.value %}
<tr>
<td><code>{{ attribute.name }}</code></td>
<td>
{% if attribute.annotation %}
{% with expression = attribute.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
{% endif %}
</td>
<td>
<div class="doc-md-description">
{{ attribute.description|convert_markdown(heading_level, html_id) }}
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock table_style %}
{% elif config.docstring_section_style == "list" %}
{% block list_style %}
<p class="pythonista-docs-heading">{{ section.title or lang.t("Attributes:") }}</p>
<ul>
{% for attribute in section.value %}
<li class="field-body">
<b>{{ attribute.name }}</b>
{% if attribute.annotation %}
{% with expression = attribute.annotation %}
(<code>{% include "expression.html" with context %}</code>)
{% endwith %}
{% endif %}
–
<div class="doc-md-description">
{{ attribute.description|convert_markdown(heading_level, html_id) }}
</div>
</li>
{% endfor %}
</ul>
{% endblock list_style %}
{% elif config.docstring_section_style == "spacy" %}
{% block spacy_style %}
<table>
<thead>
<tr>
<th><b>{{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }}</b></th>
<th><b>{{ lang.t("DESCRIPTION") }}</b></th>
</tr>
</thead>
<tbody>
{% for attribute in section.value %}
<tr>
<td><code>{{ attribute.name }}</code></td>
<td class="doc-attribute-details">
<div class="doc-md-description">
{{ attribute.description|convert_markdown(heading_level, html_id) }}
</div>
<p>
{% if attribute.annotation %}
<span class="doc-attribute-annotation">
<b>TYPE:</b>
{% with expression = attribute.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
</span>
{% endif %}
</p>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock spacy_style %}
{% endif %}
{% extends "_base/docstring/attributes.html" %}
{% block contents %}
{% block list_style scoped %}
<ul>
{% for attribute in section.value %}
<li class="field-body">
<b><code><a href="#{{ obj.path }}.{{ attribute.name }}" data-autorefs-optional-hover="{{ obj.path }}.{{ attribute.name }}">{{ attribute.name }}</a></code></b>
{% if attribute.annotation %}
{% with expression = attribute.annotation %}
(<code>{% include "expression.html" with context %}</code>)
{% endwith %}
{% endif %}
–
<div class="doc-md-description">
{{ attribute.description|convert_markdown(heading_level, html_id) }}
</div>
</li>
{% endfor %}
</ul>
{% endblock list_style %}
{% endblock contents %}

0 comments on commit 5a4be9b

Please sign in to comment.