Skip to content

Init reference doc generation #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gewenyu99 merged 9 commits into from
Jul 15, 2025
Merged

Init reference doc generation #280

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
5673e6e
Init spec generation
gewenyu99 Jul 8, 2025
8f92776
Discard changes to uv.lock
gewenyu99 Jul 8, 2025
2598e98
Refactor to /bin, run ruff format
gewenyu99 Jul 9, 2025
3764b41
void doesn't exist in python
gewenyu99 Jul 9, 2025
9c283c4
Address review comments
gewenyu99 Jul 9, 2025
9eedab7
Fix mypy issues
gewenyu99 Jul 9, 2025
8ba9f26
Add better type info
gewenyu99 Jul 9, 2025
e277713
Fix mypy linter errors
gewenyu99 Jul 9, 2025
12f06e5
Fix flush/join instructions
gewenyu99 Jul 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,4 @@ posthog-analytics
pyrightconfig.json
.env
.DS_Store
posthog-python-references.json
Copy link
Contributor

@greptile-apps greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: Add newline at end of file to follow Git best practices

80 changes: 80 additions & 0 deletions docs/doc_constant.py
View file
Open in desktop
Copy link
Member

@rafaeelaudibert rafaeelaudibert Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have an RFC that states we should use the bin folder for scripts. Can you add that there instead? I'd be happy with a bin/docs executable, and then maybe a bin/docs folder with your helper scripts. How does that sound?

I'm looking for the RFC and can link it to you if I find it

Copy link
Collaborator

@haacked haacked Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog/requests-for-comments#309

Copy link
Contributor Author

@gewenyu99 gewenyu99 Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes ofc, let me go through suggestions. thanks as always for sitting through reviews of code like this, my eyes started watering near the end of this.

Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
#!/usr/bin/env python3
"""
Constants for PostHog Python SDK documentation generation.
"""

# Types that are built-in to Python and don't need to be documented
NO_DOCS_TYPES = [
"Client",
Copy link
Contributor

@greptile-apps greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

logic: 'Client' probably shouldn't be in NO_DOCS_TYPES since it's a core SDK class that needs documentation

Copy link
Contributor Author

@gewenyu99 gewenyu99 Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not relevant this is only for object types. We don't need to self-reference.

"any",
"int",
"float",
"bool",
"dict",
"list",
"str",
"tuple",
"set",
"frozenset",
"bytes",
"bytearray",
"memoryview",
"range",
"slice",
"complex",
"Union",
"Optional",
"Any",
"Callable",
"Type",
"TypeVar",
"Generic",
"Literal",
"ClassVar",
"Final",
"Annotated",
"NotRequired",
"Required",
"void",
"None",
"NoneType",
"object",
"Unpack",
"BaseException",
"Exception",
]

# Documentation generation metadata
DOCUMENTATION_METADATA = {
"hogRef": "0.1",
"slugPrefix": "posthog-python",
"specUrl": "https://github.com/PostHog/posthog-python"
}

# Docstring parsing patterns for new format
DOCSTRING_PATTERNS = {
"examples_section": r'Examples:\s*\n(.*?)(?=\n\s*\n\s*Category:|\Z)',
"args_section": r'Args:\s*\n(.*?)(?=\n\s*\n\s*Examples:|\n\s*\n\s*Details:|\n\s*\n\s*Category:|\Z)',
"details_section": r'Details:\s*\n(.*?)(?=\n\s*\n\s*Examples:|\n\s*\n\s*Category:|\Z)',
"category_section": r'Category:\s*\n\s*(.+?)\s*(?:\n|$)',
Copy link
Contributor

@greptile-apps greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

logic: These regex patterns don't handle nested sections properly. Consider using a more robust parsing approach or adding negative lookaheads to prevent incorrect matches

Copy link
Contributor Author

@gewenyu99 gewenyu99 Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noted, but we don't expect weird nesting, we'd rather fix the doc string

"code_block": r'```(?:python)?\n(.*?)```',
"param_description": r'^\s*{param_name}:\s*(.+?)(?=\n\s*\w+:|\Z)',
"args_marker": r'\n\s*Args:\s*\n',
"examples_marker": r'\n\s*Examples:\s*\n',
"details_marker": r'\n\s*Details:\s*\n',
"category_marker": r'\n\s*Category:\s*\n'
}

# Output file configuration
OUTPUT_CONFIG = {
"filename": "posthog-python-references.json",
"indent": 2
Copy link
Contributor

@greptile-apps greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: Add a path variable for output directory instead of just filename to make the output location configurable

}

# Documentation structure defaults
DOC_DEFAULTS = {
"showDocs": True,
"releaseTag": "public",
"return_type_void": "void",
Copy link
Contributor

@greptile-apps greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: Consider using 'None' instead of 'void' for return_type_void to align with Python conventions

Suggested change
"return_type_void": "void",
"return_type_void": "None",

Copy link
Member

@rafaeelaudibert rafaeelaudibert Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be None like the bot is suggesting?

Copy link
Contributor Author

@gewenyu99 gewenyu99 Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yah probably, this is a left over from the TS specs. void isn't a thing here

"max_optional_params": 3
}
Loading
Loading