Broken links in Python SDK documentation with docusaurus v3

[drobnikj]

Describe the bug
All reference links in the Python SDK documentation are broken after migrating docusausus to v3. For example, on the storages concept page, none of the links to reference materials are functioning correctly.

To Reproduce
Steps to reproduce the behavior:

1. Bump docusaurus to v3
2. Go to 'storages concept page'
3. Click on any link in the reference section.
4. Observe that the links lead to non-existent pages, resulting in a 404 error.

Expected behavior
All links in the Python SDK documentation should correctly lead to the intended reference pages without resulting in errors.

Where was this bug reported
https://apify.slack.com/archives/C0L33UM7Z/p1725871628149089

[barjin]

A closer investigation shows that this is not caused by the Docusaurus v3 update but by changes to the actual code base.

See e.g. 2f9dcc5 - this turns Actor from a class to a global variable and moves the class definition into _ActorType (which is a "private" name, by pydoc-markdown's standards).

I'm not too sure how to handle this. In a perfect world, the project architecture would play nicely with how we document things (and how it's understandable for users), but I get that this is not always possible.

Maybe a question for @janbuchar - with the static Actor instance now, how would you expect to see this in the docs? Can we consider the Actor instance a "class" with all static methods for the sake of documentation? Or are there other caveats?

[janbuchar]

@barjin the reason for the change was to avoid bending the Python object mechanics too much. This was hard to read and maintain. If you know a way to make the docs think that Actor is a "static class", I say go for it.

[barjin]

If you know a way to make the docs think that Actor is a "static class", I say go for it.

Well, it certainly can be done, but it would be just another custom hack :/

Are there any other places with such changes that you can think of? All the storage clients are missing their methods too 🤔

[janbuchar]

If you know a way to make the docs think that Actor is a "static class", I say go for it.

Well, it certainly can be done, but it would be just another custom hack :/

Less hacks in the code, more hacks in the docs... I guess we just can't have nice things.

Are there any other places with such changes that you can think of? All the storage clients are missing their methods too 🤔

That do be weird - https://github.com/apify/apify-sdk-python/blob/master/src/apify/apify_storage_client/_dataset_client.py - I can see the methods there. I don't think any such changes are intentional, but see the upgrading guide for a comprehensive list of changes.

Ah, it's probably because Dataset, RequestQueue and KeyValueStore are now just re-exports from Crawlee.