apify
docs: messy rendering of edited types
If the parameter / return type is wrapped in utility types (adding / omitting / excluding some properties or types), the Docusaurus plugin resolves the utility types, which results in a (factually) correct, but messy docs:
https://github.com/apify/crawlee/blob/cfdf6da27fa5ed049a49f3d348a5db0015f3dd6b/packages/core/src/enqueue_links/enqueue_links.ts#L274-L282
(note that the requestQueue param is missing and the urls param is required)
Unfortunately, I see the follwoing as the only way out right now - any more complex type resolving in the docusaurus typedoc plugin seems tedious and much more error prone.
An easy way out - we can stop using inlined utility types and create separate exported interfaces for each "edited" type:
These will render nicely in the docs (compare with the screenshot from the original issue):
| method page | separate interface page |
|---|---|
The downside is the added code verbosity and a bunch of new, almost duplicate, "Interface" pages in the docs. wdyt @janbuchar @B4nan - is the docs clarity worth the added bloat?
The downside is the added code verbosity and a bunch of new, almost duplicate, "Interface" pages in the docs. wdyt @janbuchar @B4nan - is the docs clarity worth the added bloat?
In my opinion it's not. Having to come up with a name for each of these new types would be a serious pain, and it would inevitably lead to confusion because of similarly callled types.
