Conversation
- Automated documentation category generation in `compiler/docs/compiler.py` using directory structure and AST discovery. - Reorganized `pyrogram/methods/` and `pyrogram/types/` into subdirectories (stories, bots, bot_commands, etc.) for better categorization. - Enhanced `docs/source/conf.py` with `sphinx_immaterial` theme, indigo palette, and social links. - Improved `docs/source/_static/css/custom.css` with better dark mode support and styled UI badges. - Maintained backward compatibility via proxy imports and comprehensive `__all__` in `pyrogram/types/__init__.py`. - Updated `pyrogram/filters.py` to use proper type imports from the package. Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Signed-off-by: 5hojib <yesiamshojib@gmail.com>
Contributor
Reviewer's GuideRefactors documentation generation for Pyrogram/Electrogram APIs to be dynamically discovered from the codebase (methods, types, bound methods, enums), modernizes Sphinx/MkDocs styling and theme configuration, and updates type/method modules to align with new docs structure (including stories methods and expanded types exports). Class diagram for updated methods and types structureclassDiagram
direction LR
class Methods {
}
class Users {
}
class Stories {
}
class DeleteAccount {
}
class BlockUser {
}
class GetCommonChats {
}
class GetChatPhotos {
}
class GetChatPhotosCount {
}
class SetProfilePhoto {
}
class DeleteProfilePhotos {
}
class GetUsers {
}
class GetMe {
}
class SetUsername {
}
class UnblockUser {
}
class UpdateBirthday {
}
class UpdatePersonalChat {
}
class UpdateProfile {
}
class GetDefaultEmojiStatuses {
}
class SetEmojiStatus {
}
class DeleteStories {
}
class EditStory {
}
class ExportStoryLink {
}
class ForwardStory {
}
class GetAllStories {
}
class GetPeerStories {
}
class GetStories {
}
class GetUserStoriesHistory {
}
class SendStory {
}
Methods <|-- Users
Methods <|-- Stories
Users <|-- BlockUser
Users <|-- DeleteAccount
Users <|-- GetCommonChats
Users <|-- GetChatPhotos
Users <|-- GetChatPhotosCount
Users <|-- SetProfilePhoto
Users <|-- DeleteProfilePhotos
Users <|-- GetUsers
Users <|-- GetMe
Users <|-- SetUsername
Users <|-- UnblockUser
Users <|-- UpdateBirthday
Users <|-- UpdatePersonalChat
Users <|-- UpdateProfile
Users <|-- GetDefaultEmojiStatuses
Users <|-- SetEmojiStatus
Stories <|-- DeleteStories
Stories <|-- EditStory
Stories <|-- ExportStoryLink
Stories <|-- ForwardStory
Stories <|-- GetAllStories
Stories <|-- GetPeerStories
Stories <|-- GetStories
Stories <|-- GetUserStoriesHistory
Stories <|-- SendStory
class TypesPackage {
<<module>>
+__all__ exports
+users_and_chats
+messages_and_media
+bots_and_keyboards
+payments
+stories
}
class StoriesTypesModule {
<<module>>
+Story
+StoryDeleted
+StoryForwardHeader
+StorySkipped
+StoryViews
+StoriesPrivacyRules
+MediaArea
+MediaAreaChannelPost
+MediaAreaCoordinates
+InputMediaArea
+InputMediaAreaChannelPost
}
TypesPackage o-- StoriesTypesModule
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 introduces a major architectural improvement to the documentation generation system, transitioning from a manual, list-based approach to an automated, code-driven discovery mechanism. This change enhances the accuracy and maintainability of the API reference documentation by directly reflecting the library's structure. Concurrently, it streamlines the internal organization of various library components, particularly those related to stories and bots, into more logical and distinct modules. The user-facing documentation also receives a visual refresh with updated styling and theme colors. 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}
Contributor
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- The new dynamic API docs generation has quite a bit of duplicated path resolution logic (top-level constants vs overrides in
start()and repeatedif not path.exists(): path = Path('../../') / ...blocks); consider centralizing this into a single helper that resolves all base paths consistently to reduce confusion and future breakage when paths change. - The
pyrogram/types/__init__.py__all__list is now a very long manually maintained list that can easily get out of sync with the actual submodules; consider generating it programmatically from the imported subpackages (e.g., by aggregating their__all__or usingpkgutil) to improve maintainability.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new dynamic API docs generation has quite a bit of duplicated path resolution logic (top-level constants vs overrides in `start()` and repeated `if not path.exists(): path = Path('../../') / ...` blocks); consider centralizing this into a single helper that resolves all base paths consistently to reduce confusion and future breakage when paths change.
- The `pyrogram/types/__init__.py` `__all__` list is now a very long manually maintained list that can easily get out of sync with the actual submodules; consider generating it programmatically from the imported subpackages (e.g., by aggregating their `__all__` or using `pkgutil`) to improve maintainability.
## Individual Comments
### Comment 1
<location> `compiler/docs/compiler.py:380-381` </location>
<code_context>
+ f.write(".. code-block:: python\n\n")
+ f.write(" from pyrogram import Client\n\n")
+ f.write(' app = Client("my_account")\n\n\n')
+ f.write(" @app.on_message()\n")
+ f.write(" def hello(client, message)\n")
+ f.write(' message.reply("hi")\n\n\n')
+ f.write(" app.run()\n\n")
</code_context>
<issue_to_address>
**issue (bug_risk):** Example code for bound methods has a syntax error (missing colon after the function definition).
The emitted example is invalid Python because `def hello(client, message)` is missing the colon. Please update that line in the generated string to `def hello(client, message):` so the example runs as-is when copied.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+380
to
+381
| f.write(" @app.on_message()\n") | ||
| f.write(" def hello(client, message)\n") |
Contributor
There was a problem hiding this comment.
issue (bug_risk): Example code for bound methods has a syntax error (missing colon after the function definition).
The emitted example is invalid Python because def hello(client, message) is missing the colon. Please update that line in the generated string to def hello(client, message): so the example runs as-is when copied.
![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 is a major and impressive refactoring of the documentation generation system. It moves from a hardcoded, manual approach to a dynamic one that discovers API methods, types, and enums from the source code. This significantly improves maintainability. The code organization is also improved by moving story-related methods and various types into their own dedicated packages. The changes are well-executed. I have a couple of suggestions for the documentation compiler script to improve its robustness and reduce code duplication.
Comment on lines
+141
to
+143
| methods_path = Path(METHODS_PATH) | ||
| if not methods_path.exists(): | ||
| methods_path = Path("../../") / METHODS_PATH |
There was a problem hiding this comment.
The logic for resolving source paths is repeated for methods_path, types_lib_path (lines 173-175), and enums_lib_path (lines 224-226). To follow the DRY (Don't Repeat Yourself) principle and improve maintainability, this logic can be extracted into a helper function.
For example, you could define a helper function like this:
def get_source_path(relative_path: str) -> Path:
"""Gets the correct path whether run from root or compiler/docs."""
path = Path(relative_path)
if not path.exists():
return Path("../../") / relative_path
return pathAnd then use it like this:
methods_path = get_source_path(METHODS_PATH)
Comment on lines
+187
to
+188
| except Exception: | ||
| continue |
There was a problem hiding this comment.
Using except Exception: is too broad and can mask unexpected errors. It's better to catch a more specific exception. Since ast.parse() is being called, SyntaxError is the most likely and relevant exception to handle here. This also applies to other similar try...except blocks in this file (e.g., lines 204-207 and 233-236).
Suggested change
| except Exception: | |
| continue | |
| except SyntaxError: | |
| continue |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by Sourcery
Automate API docs generation from the codebase and align documentation, type exports, and method groupings with the current Electrogram feature set.
New Features:
Enhancements:
Documentation: