Skip to content

Commit 4541307

Browse files
HitaloMHitaloM
authored
docs: improvements and fixes (#19)
* docs: fixed typos in the contributing guide * fix: tgcrypto link in speedups doc * refactor: improved sphinx configuration * refactor: changed copyright holder of pyromod The PR of Pyromod implementation (#1) was submitted before the change in organization and copyright holder. As a result, we forgot to update the holder information in the files from Amano LLC to Hydrogram. * docs: use correct category for news fragment 15 * Merge branch 'dev' of https://github.com/hydrogram/hydrogram into docs-improvements * chore: update furo to 2024.1.29 * docs: fixed a typo in github url * docs: disable `napoleon_preprocess_types` It was causing problems with the formatting of the types in the documentation pages * docs(contributing): improved feedback and commits section * Merge branch 'dev' of https://github.com/hydrogram/hydrogram into docs-improvements * fix(news): fixed a typo * chore: update sphinx-autobuild * docs: added mtproto-vs-bot-api image
1 parent 51bcd62 commit 4541307

30 files changed

+85
-101
lines changed

‎CONTRIBUTING.md‎

Lines changed: 30 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@ If you have a question, please use the [discussions](https://github.com/orgs/hyd
1212

1313
## Providing Feedback
1414

15-
Feedback from the community is very important to us at Hydrogram. You can share your thoughts and suggestions by creating [discussions](https://github.com/orgs/hydrogram/discussions).
15+
Feedback from the community is very important to us at Hydrogram. If you have any suggestions, ideas, or concerns, please share them with us. You can use the [discussions](https://github.com/orgs/hydrogram/discussions) to start a conversation.
16+
17+
You might be wondering about the difference between asking questions, providing feedback, and making feature requests. Asking questions is about seeking help or clarification. Providing feedback involves sharing your thoughts and opinions on the existing features and the project as a whole. Feature requests, on the other hand, are about suggesting new features or improvements. See the next section for more details on feature requests.
1618

1719
## Creating Issues
1820

@@ -60,64 +62,70 @@ You can read more about pull requests in the [GitHub docs](https://docs.github.c
6062
1. Fork the Hydrogram repository to your GitHub account.
6163
2. Clone your forked repository of Hydrogram to your computer:
6264

63-
bash```
64-
git clone <https://github.com/><your username>/hydrogram
65-
cd hydrogram```
65+
```bash
66+
git clone https://github.com/<your username>/hydrogram
67+
cd hydrogram
68+
```
6669

6770
4. Add a track to the original repository:
6871

69-
bash```
70-
git remote add upstream <https://github.com/hydrogram/hydrogram>```
72+
```bash
73+
git remote add upstream https://github.com/hydrogram/hydrogram
74+
```
7175

7276
5. Install dependencies:
7377

7478
Hydrogram uses and recommends [Rye](https://rye-up.com/) for managing virtual environmens and dependencies.
7579

76-
bash```
77-
rye sync --all-features```
80+
```bash
81+
rye sync --all-features
82+
```
7883

7984
> We use `--all-features` to install all the optional dependencies, which are required to run the tests and build the documentation.
8085
8186
6. Install pre-commit hooks:
8287

8388
[Pre-commit](https://pre-commit.com/) is a tool that runs various checks before you make a commit. It helps you avoid committing any errors or warnings that might break your code or violate the coding standards.
8489

85-
bash```
86-
pre-commit install```
90+
```bash
91+
pre-commit install
92+
```
8793

8894
### Format the code (code-style)
8995

9096
Hydrogram uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting the code to maintain it consistent and clean. You should [install](https://docs.astral.sh/ruff/installation/) and run Ruff on your code before committing:
9197

92-
bash```
93-
ruff check .```
98+
```bash
99+
ruff check .
100+
```
94101

95102
However, you can also rely on [pre-commit](https://pre-commit.com/) for it:
96103

97-
bash```
98-
pre-commit run --run-all-files```
104+
```bash
105+
pre-commit run --run-all-files
106+
```
99107

100108
### Run tests
101109

102110
All changes should be tested:
103111

104-
bash```
105-
pytest tests```
112+
```bash
113+
pytest tests
114+
```
106115

107116
Remember to write tests for your new features or modify the existing tests to cover your code changes. Testing is essential to ensure the quality and reliability of your code.
108117

109118
### Docs
110119

111120
We use Sphinx to generate documentation in the `docs` directory. You can edit the sources and preview the changes using a live-preview server with:
112121

113-
bash```
114-
sphinx-autobuild docs/source/ docs/build/ --watch hydrogram/```
122+
```bash
123+
sphinx-autobuild docs/source/ docs/build/ --watch hydrogram/
124+
```
115125

116126
### Commit Messages
117127

118-
We use conventional commits, which provide a standardized and structured format for commit messages. This helps ensure clear and consistent communication about the changes made in each commit.
119-
120-
- **Commit messages**: The commit messages should follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification, which provides a structured and consistent format for describing the changes in the commits. The commit messages should have the following structure:
128+
We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), which provide a standardized and structured format for commit messages. This helps ensure clear and consistent communication about the changes made in each commit. The commit messages should have the following structure:
121129

122130
```
123131
<type>[optional scope]: <description>
@@ -158,7 +166,7 @@ Write a concise summary of your changes in one or more sentences, so that bot de
158166
- `feature` - when you add a new feature
159167
- `bugfix` - when you fix a bug
160168
- `doc` - when you improve the documentation
161-
- `removal` - when you remove something from the library968sm6
169+
- `removal` - when you remove something from the library
162170
- `misc` - when you change something in the core or the project configuration
163171

164172
If you are not sure which category to use, you can ask the core contributors for help.

‎cherry-pick-pyro.sh‎

100755100644
File mode changed.

‎docs/source/_static/img/mtproto-vs-bot-api.png‎

11.9 KB
Loading

‎docs/source/conf.py‎

Lines changed: 27 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,16 @@
1-
# Configuration file for the Sphinx documentation builder.
2-
#
3-
# For the full list of built-in configuration values, see the documentation:
4-
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5-
6-
# -- Project information -----------------------------------------------------
7-
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8-
9-
import re
1+
import datetime
102
import sys
113
from pathlib import Path
124

13-
project = "Hydrogram"
14-
copyright = "2023-present, Hydrogram."
15-
author = "Hydrogram"
16-
175
docs_dir = Path(__file__).parent.parent
186
sys.path.insert(0, docs_dir.resolve().as_posix())
197

20-
# Find the version and release information.
21-
# We have a single source of truth for our version number: pip's __init__.py file.
22-
# This next bit of code reads from it.
23-
file_with_version = Path(docs_dir / ".." / "hydrogram" / "__init__.py")
24-
with Path(file_with_version).open() as f:
25-
for line in f:
26-
if m := re.match(r'__version__ = "(.*)"', line):
27-
__version__ = m[1]
28-
# The short X.Y version.
29-
version = ".".join(__version__.split(".")[:2])
30-
# The full version, including alpha/beta/rc tags.
31-
release = __version__
32-
break
33-
else: # AKA no-break
34-
version = release = "dev"
8+
import hydrogram # noqa: E402
359

36-
# -- General configuration ---------------------------------------------------
37-
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
10+
project = "Hydrogram"
11+
author = "Hydrogram"
12+
copyright = f"{datetime.date.today().year}, {author}"
13+
release = hydrogram.__version__
3814

3915
extensions = [
4016
"sphinx.ext.autodoc",
@@ -48,38 +24,40 @@
4824

4925
intersphinx_mapping = {
5026
"python": ("https://docs.python.org/3", None),
27+
"aiosqlite": ("https://aiosqlite.omnilib.dev/en/stable/", None),
5128
}
5229

53-
master_doc = "index"
54-
source_suffix = ".rst"
55-
autodoc_member_order = "bysource"
30+
html_use_modindex = False
31+
html_use_index = False
5632

5733
napoleon_use_rtype = False
5834
napoleon_use_param = False
5935

36+
master_doc = "index"
37+
source_suffix = ".rst"
38+
autodoc_member_order = "bysource"
39+
autodoc_typehints = "none"
40+
6041
towncrier_draft_autoversion_mode = "draft"
6142
towncrier_draft_include_empty = True
6243
towncrier_draft_working_directory = Path(__file__).parent.parent.parent
6344

64-
# The name of the Pygments (syntax highlighting) style to use.
65-
pygments_style = "sphinx"
45+
pygments_style = "friendly"
6646

67-
# Decides the language used for syntax highlighting of code blocks.
68-
highlight_language = "python3"
47+
html_theme = "furo"
48+
html_title = f"{project} v{release} Documentation"
49+
html_last_updated_fmt = (
50+
f"{datetime.datetime.now(tz=datetime.UTC).strftime('%d/%m/%Y, %H:%M:%S')} UTC"
51+
)
6952

70-
# -- Options for HTML output -------------------------------------------------
71-
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
53+
html_copy_source = False
7254

73-
html_theme = "furo"
74-
html_title = f"{project} documentation v{release}"
7555
html_static_path = ["_static"]
7656
html_css_files = [
7757
"css/all.min.css",
7858
"css/custom.css",
7959
]
8060

81-
# Theme options are theme-specific and customize the look and feel of a theme
82-
# further. For a list of options available for each theme, see the documentation.
8361
html_theme_options = {
8462
"navigation_with_keys": True,
8563
"dark_css_variables": {
@@ -92,12 +70,10 @@
9270
},
9371
"light_logo": "hydrogram-light.png",
9472
"dark_logo": "hydrogram-dark.png",
95-
"footer_icons": [
73+
"footer_icons": [ # all these icons are from https://react-icons.github.io/react-icons
9674
{
97-
# Telegram channel logo
9875
"name": "Telegram Channel",
9976
"url": "https://t.me/HydrogramNews/",
100-
# Following svg is from https://react-icons.github.io/react-icons/search?q=telegram
10177
"html": (
10278
'<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
10379
'viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">'
@@ -113,9 +89,9 @@
11389
),
11490
"class": "",
11591
},
116-
{ # Github logo
117-
"name": "GitHub",
118-
"url": "https://github.com/hydrogram/hydrogram/",
92+
{
93+
"name": "GitHub Organization",
94+
"url": "https://github.com/hydrogram/",
11995
"html": (
12096
'<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
12197
'viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 '
@@ -130,8 +106,8 @@
130106
),
131107
"class": "",
132108
},
133-
{ # PTB website logo - globe
134-
"name": "python-telegram-bot website",
109+
{
110+
"name": "Hydrogram Website",
135111
"url": "https://hydrogram.org/",
136112
"html": (
137113
'<svg stroke="currentColor" fill="currentColor" stroke-width="0" '

‎docs/source/topics/speedups.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,5 +79,5 @@ The ``uvloop.install()`` call also needs to be placed before creating a Client i
7979
8080
app.run()
8181
82-
.. _TgCrypto: https://github.com/hydrogram/tgcrypto
82+
.. _TgCrypto: https://github.com/pyrogram/tgcrypto
8383
.. _uvloop: https://github.com/MagicStack/uvloop

‎hydrogram/errors/pyromod/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2020-present Cezar H. <https://github.com/usernein>
3-
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
3+
# Copyright (C) 2023-present Hydrogram <https://hydrogram.org>
44
#
55
# This file is part of Hydrogram.
66
#

‎hydrogram/errors/pyromod/listener_stopped.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2020-present Cezar H. <https://github.com/usernein>
3-
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
3+
# Copyright (C) 2023-present Hydrogram <https://hydrogram.org>
44
#
55
# This file is part of Hydrogram.
66
#

‎hydrogram/errors/pyromod/listener_timeout.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2020-present Cezar H. <https://github.com/usernein>
3-
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
3+
# Copyright (C) 2023-present Hydrogram <https://hydrogram.org>
44
#
55
# This file is part of Hydrogram.
66
#

‎hydrogram/helpers/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2020-present Cezar H. <https://github.com/usernein>
3-
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
3+
# Copyright (C) 2023-present Hydrogram <https://hydrogram.org>
44
#
55
# This file is part of Hydrogram.
66
#

‎hydrogram/helpers/helpers.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2020-present Cezar H. <https://github.com/usernein>
3-
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
3+
# Copyright (C) 2023-present Hydrogram <https://hydrogram.org>
44
#
55
# This file is part of Hydrogram.
66
#

0 commit comments

Comments
 (0)