Skip to content

Conversation

allenporter
Copy link
Contributor

Add pdoc, which is similar to the existing documentation, but uses existing python docstrings as the basis for documentation, then can also include markdown files. This PR creates a pdoc documentation site within the existing documentation directory for initial testing.

Feel free to reject if this is not useful given we already have some documentation. This may be considered just personal preference.

Example site: https://allenporter.github.io/ical/ical.html
See https://pdoc.dev/docs/pdoc.html for more background on how pdoc works.

@allenporter allenporter requested a review from Lash-L September 28, 2025 01:48
Copy link
Collaborator

@Lash-L Lash-L left a comment

Choose a reason for hiding this comment

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

I think this definitely makes more sense than what we have now. It is the best chance of docs actually getting updated and helps make better documentation in the code.

Are we able to include something like the RoborockCommand enum? Can we even get more granular and attempt to doc each entry in a enum? Or is that above what pydoc is capable of

@allenporter
Copy link
Contributor Author

Are we able to include something like the RoborockCommand enum? Can we even get more granular and attempt to doc each entry in a enum? Or is that above what pydoc is capable of

You can add a docstring for each enum value so it can be self documenting. I think it works very well for fine grained documentation.

Maybe then as part of the transition we can either copy or move the existing API docs to the Python code. Or we can also leave it in the protocol directory.

@allenporter allenporter merged commit 21c83c0 into Python-roborock:main Sep 29, 2025
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants