Improve Docs, Auto Generate Enums Index, and Modernize UI#68
Conversation
- Updated `compiler/docs/compiler.py` to support categorized Enums. - Enhanced documentation visuals with modern fonts (Inter, JetBrains Mono) and theme features (instant navigation). - Refined `docs/source/_static/css/custom.css` for a modern minimalist UI with backdrop-filter blurs and improved typography. - Improved `docs/source/index.rst` layout for a better first impression. - Fixed typo in enum filename: renamed `listerner_types.py` to `listener_types.py`. - Regenerated all API and documentation files. Co-authored-by: 5hojib <107526130+5hojib@users.noreply.github.com>
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
Reviewer's GuideUpdates the documentation build to auto-categorize enums, modernizes the Sphinx theme and custom CSS, refreshes the homepage and enum API pages, and fixes a listener types filename typo across the codebase. Flow diagram for auto categorized enums index generationflowchart TD
A[Start pyrogram_api] --> B[Collect enums_list from pyrogram.enums]
B --> C[Initialize categorized_enums and assigned_enums]
C --> D[Iterate over ENUMS_CATEGORIES]
D --> E[For each category title and enum list]
E --> F[Filter enums present in enums_list]
F --> G{Filtered list empty?}
G -- Yes --> D
G -- No --> H[Add sorted filtered list to categorized_enums]
H --> I[Add enums to assigned_enums]
I --> D
D --> J[Compute others = enums_list minus assigned_enums]
J --> K{others non empty?}
K -- Yes --> L[Add Others category to categorized_enums]
K -- No --> M[Skip Others category]
L --> N[Iterate over categorized_enums items]
M --> N
N --> O[For each category: write section title and underline]
O --> P[Write autosummary directive with category enums]
P --> Q[Write hidden toctree entries for category enums]
Q --> R[Repeat for all categories]
R --> S[For each enum in enums_list]
S --> T[Write individual enum .rst file]
T --> U[End pyrogram_api]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Summary of ChangesHello @5hojib, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the documentation experience by introducing automated categorization for enums, modernizing the user interface with updated styling and theme configurations, and refining the homepage layout. These changes aim to improve navigation, readability, and overall aesthetic appeal of the documentation. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- The
ENUMS_CATEGORIESmapping incompiler/docs/compiler.pyhard-codes enum names and categories, which can easily drift out of sync with the actual enums; consider deriving this list dynamically (e.g., via introspection or a simple config structure closer to the enums) or at least centralizing it so enums can be renamed/added without updating the compiler logic. - The new CSS introduces a 0.75rem base font size and heavy use of
backdrop-filterblur, which can impact readability and performance on some devices; it might be worth revisiting these values (or addingprefers-reduced-motion/prefers-reduced-transparency-style guards) to keep the UI accessible and performant.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The `ENUMS_CATEGORIES` mapping in `compiler/docs/compiler.py` hard-codes enum names and categories, which can easily drift out of sync with the actual enums; consider deriving this list dynamically (e.g., via introspection or a simple config structure closer to the enums) or at least centralizing it so enums can be renamed/added without updating the compiler logic.
- The new CSS introduces a 0.75rem base font size and heavy use of `backdrop-filter` blur, which can impact readability and performance on some devices; it might be worth revisiting these values (or adding `prefers-reduced-motion`/`prefers-reduced-transparency`-style guards) to keep the UI accessible and performant.
## Individual Comments
### Comment 1
<location> `docs/source/_static/css/custom.css:14-17` </location>
<code_context>
}
+/* Modern Header with blur */
+.md-header {
+ backdrop-filter: blur(20px);
+ -webkit-backdrop-filter: blur(20px);
+ background-color: rgba(63, 81, 181, 0.85);
+}
+
</code_context>
<issue_to_address>
**suggestion (performance):** The use of `backdrop-filter` on the header can negatively impact performance and is not supported in all browsers without a clear fallback.
On sticky headers this level of blur can be costly, particularly on low‑end devices and during scroll, and some browsers will ignore it entirely. Consider adding a solid background fallback with a feature query (`@supports (backdrop-filter: blur(1px)) { ... }`), reducing the blur radius, or turning off the blur on small screens via media queries.
</issue_to_address>
### Comment 2
<location> `docs/source/index.rst:39` </location>
<code_context>
-in the top left corner.
-
-Here below you can, instead, find a list of the most relevant pages for a quick access.
+Contents are organized into sections composed of self-contained topics which can be all accessed from the sidebar.
+Here below you can find a list of the most relevant pages for quick access.
</code_context>
<issue_to_address>
**suggestion (typo):** Consider adjusting word order in "can be all accessed" for more natural phrasing.
The phrase "which can be all accessed from the sidebar" is understandable but slightly awkward. Consider "which can all be accessed from the sidebar" for more natural phrasing.
```suggestion
Contents are organized into sections composed of self-contained topics which can all be accessed from the sidebar.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| .md-header { | ||
| backdrop-filter: blur(20px); | ||
| -webkit-backdrop-filter: blur(20px); | ||
| background-color: rgba(63, 81, 181, 0.85); |
There was a problem hiding this comment.
suggestion (performance): The use of backdrop-filter on the header can negatively impact performance and is not supported in all browsers without a clear fallback.
On sticky headers this level of blur can be costly, particularly on low‑end devices and during scroll, and some browsers will ignore it entirely. Consider adding a solid background fallback with a feature query (@supports (backdrop-filter: blur(1px)) { ... }), reducing the blur radius, or turning off the blur on small screens via media queries.
| in the top left corner. | ||
|
|
||
| Here below you can, instead, find a list of the most relevant pages for a quick access. | ||
| Contents are organized into sections composed of self-contained topics which can be all accessed from the sidebar. |
There was a problem hiding this comment.
suggestion (typo): Consider adjusting word order in "can be all accessed" for more natural phrasing.
The phrase "which can be all accessed from the sidebar" is understandable but slightly awkward. Consider "which can all be accessed from the sidebar" for more natural phrasing.
| Contents are organized into sections composed of self-contained topics which can be all accessed from the sidebar. | |
| Contents are organized into sections composed of self-contained topics which can all be accessed from the sidebar. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly improves the documentation by automating the generation of a categorized enum index, modernizing the UI with a new theme configuration and custom CSS, and refining the homepage layout. The changes make the documentation more organized and visually appealing. I've found a couple of areas for improvement in the CSS and HTML implementation to enhance maintainability. Specifically, I've suggested replacing inline styles with CSS classes and reviewing the use of !important in the custom stylesheet. Overall, this is a great set of enhancements for the project's documentation.
| .highlight { | ||
| border-radius: 8px !important; | ||
| border: 1px solid rgba(0, 0, 0, 0.05) !important; | ||
| transition: box-shadow 0.3s ease; | ||
| } | ||
|
|
||
| .highlight:hover { | ||
| box-shadow: 0 4px 12px rgba(0, 0, 0, 0.05); | ||
| } | ||
|
|
||
| [data-md-color-scheme="slate"] .highlight { | ||
| border-color: rgba(255, 255, 255, 0.05) !important; | ||
| } |
There was a problem hiding this comment.
The use of !important on lines 42, 43, and 52 should be avoided if possible. It can lead to maintenance issues by breaking the natural CSS cascade. Consider increasing selector specificity to override the theme's styles. For instance, you might be able to use a selector like .md-content .highlight which could be specific enough to not require !important.
| <div style="display: flex; align-items: center; gap: 20px; margin-top: 1rem; margin-bottom: 1.5rem;"> | ||
| <div> | ||
| <p style="margin: 0; font-size: 1.2rem; font-weight: 500; opacity: 0.9;"> | ||
| Modern MTProto API Framework for Python | ||
| </p> | ||
| <div style="margin-top: 12px; display: flex; gap: 8px;"> | ||
| <a href="https://github.com/5hojib/Electrogram" style="padding: 4px 14px; background: var(--md-primary-fg-color); color: white; border-radius: 20px; font-size: 0.75rem; font-weight: 600; text-decoration: none;">GitHub</a> | ||
| <a href="https://github.com/5hojib/Electrogram/issues" style="padding: 4px 14px; background: #f5f5f5; color: #333; border-radius: 20px; font-size: 0.75rem; font-weight: 600; text-decoration: none;">Issues</a> | ||
| </div> | ||
| </div> | ||
| </div> |
There was a problem hiding this comment.
This raw HTML block contains a lot of inline styles. To improve maintainability and separate content from presentation, it's better to move these styles into an external stylesheet (custom.css) and use CSS classes on the HTML elements. This will make the styles reusable and easier to manage.
For example, you could add the following classes to your custom.css file:
.intro-header {
display: flex;
align-items: center;
gap: 20px;
margin-top: 1rem;
margin-bottom: 1.5rem;
}
.intro-text {
margin: 0;
font-size: 1.2rem;
font-weight: 500;
opacity: 0.9;
}
.intro-buttons {
margin-top: 12px;
display: flex;
gap: 8px;
}
.button-github,
.button-issues {
padding: 4px 14px;
border-radius: 20px;
font-size: 0.75rem;
font-weight: 600;
text-decoration: none;
}
.button-github {
background: var(--md-primary-fg-color);
color: white;
}
.button-issues {
background: #f5f5f5;
color: #333;
}| <div style="display: flex; align-items: center; gap: 20px; margin-top: 1rem; margin-bottom: 1.5rem;"> | |
| <div> | |
| <p style="margin: 0; font-size: 1.2rem; font-weight: 500; opacity: 0.9;"> | |
| Modern MTProto API Framework for Python | |
| </p> | |
| <div style="margin-top: 12px; display: flex; gap: 8px;"> | |
| <a href="https://github.com/5hojib/Electrogram" style="padding: 4px 14px; background: var(--md-primary-fg-color); color: white; border-radius: 20px; font-size: 0.75rem; font-weight: 600; text-decoration: none;">GitHub</a> | |
| <a href="https://github.com/5hojib/Electrogram/issues" style="padding: 4px 14px; background: #f5f5f5; color: #333; border-radius: 20px; font-size: 0.75rem; font-weight: 600; text-decoration: none;">Issues</a> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="intro-header"> | |
| <div> | |
| <p class="intro-text"> | |
| Modern MTProto API Framework for Python | |
| </p> | |
| <div class="intro-buttons"> | |
| <a href="https://github.com/5hojib/Electrogram" class="button-github">GitHub</a> | |
| <a href="https://github.com/5hojib/Electrogram/issues" class="button-issues">Issues</a> | |
| </div> | |
| </div> | |
| </div> |
1 participant
I have improved the documentation by:
compiler/docs/compiler.pynow logically groups enums (General, Chats, Messages, etc.) in the index, making them easier to browse.sphinx_immaterialtheme configuration with faster navigation, better fonts (Inter for text, JetBrains Mono for code), and a more minimalist design.custom.cssto include modern touches like header blur effects, pill-style badges, and cleaner tables/code blocks.listerner_types.pytolistener_types.pyand updating its references.PR created automatically by Jules for task 16014549856798480274 started by @5hojib
Summary by Sourcery
Modernize the documentation UI and reorganize the enums documentation index for clearer navigation.
New Features:
Bug Fixes:
Enhancements:
Documentation: