docs: Add @docs_group decorator
#655
Conversation
src/crawlee/_utils/docs.py
Outdated
| @@ -0,0 +1,2 @@ | ||
| def docs_group(group_name: str) -> None: | ||
| pass |
There was a problem hiding this comment.
This likely breaks all the code and needs fixing.
All the "noop" decorator approaches (that work for both classes and functions) I found had way too many lines - definitely more than I'm comfortable with changing :)
Can one of you Python whizzes fix this please? (cc @vdusek @Pijukatel )
There was a problem hiding this comment.
Something like this should work:
class docs_group:
def __init__(self, group_name: str) -> None:
pass
def __call__(self, callable: Callable) -> Callable:
return callableYou could also make a function that returns a function, but I tend to find that a class is more readable.
src/crawlee/_utils/docs.py
Outdated
| @@ -0,0 +1,2 @@ | ||
| def docs_group(group_name: str) -> None: | ||
| pass |
There was a problem hiding this comment.
Something like this should work:
class docs_group:
def __init__(self, group_name: str) -> None:
pass
def __call__(self, callable: Callable) -> Callable:
return callableYou could also make a function that returns a function, but I tend to find that a class is more readable.
src/crawlee/service_container.py
Outdated
There was a problem hiding this comment.
This one is supposed to be used as a singleton:
from crawlee import service_container
client = service_container.get_storage_client()But this will probably change soon anyway...
| @@ -77,27 +79,26 @@ const groupSort = (g1, g2) => { | ||
| }; | ||
|
|
||
| function getGroupName(object) { | ||
| if (object.decorations?.some(d => d.name === 'docs_group')) { | ||
| return { | ||
| groupName: object.decorations.find(d => d.name === 'docs_group')?.args.slice(2,-2), |
There was a problem hiding this comment.
That slice is disturbing. But I guess AST parsing is overkill for this case.
Updates the `@apify/docusaurus-plugin-typedoc-api` plugin, which enables us to use the unified Python documentation pipeline (instead of handling it in each Python project separately). Decorates the symbols to be documented with `@docs_group` and `@docs_name` decorators (just like in [crawlee-python](apify/crawlee-python#655)). Those decorators could be moved up into some shared package (e.g. `apify-shared`, which already has the `@ignore_docs` decorator). Uses the new `reexports` feature of the plugin to load external API docs (from `crawlee.dev/python`) and re-render them in the current documentation instance.
Adds support for the
@docs_groupdecorator, which sets the symbol's group in the documentation.Adds the decorators as per the list in #650 .
Hides the undecorated symbols under the project root (but keeps those in classes etc., so class / object methods + properties are still documented).
Closes #650