Skip to content

[🚀 Feature]: Auto-generate the Python API from the code #14178

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.

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

Closed
emanlove opened this issue Jun 23, 2024 · 7 comments · Fixed by #15822
Closed

[🚀 Feature]: Auto-generate the Python API from the code #14178

emanlove opened this issue Jun 23, 2024 · 7 comments · Fixed by #15822
Labels
C-py Python Bindings I-enhancement Something could be better R-help wanted Issues looking for contributions

Comments

@emanlove
Copy link
Contributor

Feature and motivation

Some recent improvements have been made to the generation of the Python API documentation. Now the Python API doc is generated from the py/docs/source/api.st "template". Taking this a step further we should be able to generate the API from just the code itself. This is important as any updates to the code, for example recent additions with selenium.webdriver.common.bidi, needs to be manually added to this api.rst file, as shown here

Webdriver.common
----------------

.. currentmodule:: selenium.webdriver.common
.. autosummary::
   :toctree: webdriver

   selenium.webdriver.common.action_chains
   ...
   selenium.webdriver.common.bidi.cdp
   selenium.webdriver.common.bidi.console
   selenium.webdriver.common.bidi.script
   selenium.webdriver.common.bidi.session

And if we forgot to add, say selenium.webdriver.common.bidi.script, then it would be missing from the doc. So it would be good to either fully auto-generate it or have some automatic method to check for completeness and changes.

Usage example

Might add a step to the tox.ini to autogenerate the api doc from the code or check for completeness.

@emanlove emanlove added I-enhancement Something could be better A-needs-triaging A Selenium member will evaluate this soon! labels Jun 23, 2024
Copy link

@emanlove, thank you for creating this issue. We will troubleshoot it as soon as we can.


Info for maintainers

Triage this issue by using labels.

If information is missing, add a helpful comment and then I-issue-template label.

If the issue is a question, add the I-question label.

If the issue is valid but there is no time to troubleshoot it, consider adding the help wanted label.

If the issue requires changes or fixes from an external project (e.g., ChromeDriver, GeckoDriver, MSEdgeDriver, W3C), add the applicable G-* label, and it will provide the correct link and auto-close the issue.

After troubleshooting the issue, please add the R-awaiting answer label.

Thank you!

@titusfortner titusfortner added C-py Python Bindings R-help wanted Issues looking for contributions and removed A-needs-triaging A Selenium member will evaluate this soon! labels Jun 23, 2024
Copy link

This issue is looking for contributors.

Please comment below or reach out to us through our IRC/Slack/Matrix channels if you are interested.

@shbenzer
Copy link
Contributor

shbenzer commented Nov 1, 2024

I'm assuming we don't want to import a library for this correct? so to minimize dependencies

@emanlove
Copy link
Contributor Author

emanlove commented Nov 1, 2024

@shbenzer, I believe it can be done with the current sphinx build process without any additional packages. I am open to suggestions on other ways to do this.

Copy link

github-actions bot commented May 1, 2025

This issue is stale because it has been open 280 days with no activity. Remove stale label or comment or this will be closed in 14 days.

@github-actions github-actions bot added the J-stale Applied to issues that become stale, and eventually closed. label May 1, 2025
@cgoldberg
Copy link
Contributor

This would be a nice feature, and we did run into this situation recently. Some new modules were added, but api.rst wasn't updated, so they were missing from the docs until I manually updated it.

I haven't really looked into it, but any suggestions for auto-generating the docs without declaring modules in api.rst would be welcome.

@cgoldberg cgoldberg removed the J-stale Applied to issues that become stale, and eventually closed. label May 1, 2025
@cgoldberg
Copy link
Contributor

I just implemented this in #15822

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-py Python Bindings I-enhancement Something could be better R-help wanted Issues looking for contributions
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants