diff --git a/.gitignore b/.gitignore index fe93f81209a02..d526bf6e42c0f 100644 --- a/.gitignore +++ b/.gitignore @@ -76,6 +76,7 @@ py/selenium/webdriver/remote/isDisplayed.js py/docs/build/ py/docs/source/**/* !py/docs/source/conf.py +!py/docs/source/*.rst py/build/ py/LICENSE py/pytestdebug.log diff --git a/py/docs/.readthedocs.yaml b/py/docs/.readthedocs.yaml index 65537815914a8..5ee80bc5539f1 100644 --- a/py/docs/.readthedocs.yaml +++ b/py/docs/.readthedocs.yaml @@ -10,10 +10,11 @@ version: 2 build: os: ubuntu-24.04 tools: - python: "3.11" + python: "3.12" commands: - pip install -r py/docs/requirements.txt - pip install -r py/requirements.txt + - PYTHONPATH=py python3 py/generate_api_module_listing.py - PYTHONPATH=py sphinx-autogen -o $READTHEDOCS_OUTPUT/html py/docs/source/api.rst - PYTHONPATH=py sphinx-build -b html -d build/docs/doctrees py/docs/source $READTHEDOCS_OUTPUT/html diff --git a/py/docs/Makefile b/py/docs/Makefile deleted file mode 100644 index 2d483706c21a0..0000000000000 --- a/py/docs/Makefile +++ /dev/null @@ -1,131 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -HTML_DESTINATION = ../../docs/api/py - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: clean - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(HTML_DESTINATION) - @echo - @echo "Build finished. The HTML pages are in $(HTML_DESTINATION)." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Selenium.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Selenium.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Selenium" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Selenium" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/py/docs/README.rst b/py/docs/README.rst index f936eaa592780..772956a97d40a 100644 --- a/py/docs/README.rst +++ b/py/docs/README.rst @@ -49,22 +49,14 @@ and develop the Python docs. To clean up the build assets and tox cache ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Although there is a Sphinx Makefile option, to clean up using the tox environment above, one can -manually clean the build assets by deleting the ``build`` directory on the root (``selenium/build`` -using the default directory on git clone). Note that tox caches parts of the build and recognizes -changes to speed up the build. To start fresh, delete the aformentioned directory to clean the -Sphinx build assets and delete the ``selenium/py/.tox`` directory to clean the tox environment. +After using the tox environment above, you can clean up the build assets by deleting the ``build`` +directory in the root of the repo. Note that tox caches parts of the build and recognizes changes +to speed up the build. To start fresh, delete the ``py/.tox`` directory to clean the tox environment. Known documentation issues ========================== -The API Reference primarily builds from the source code. But currently the initial template stating -which modules to document is hard coded within ``py/docs/source/api.rst``. So if modules are added or -removed, then the generated docs will be inaccurate. It would be preferred that the API docs generate -soley from the code if possible. This is being tracked in -`#14178 `_ - We are working through the Sphinx build warnings and errors, trying to clean up both the syntax and the build. diff --git a/py/docs/source/api.rst b/py/docs/source/api.rst index 3181116d58f8a..1eb3f79d9e887 100644 --- a/py/docs/source/api.rst +++ b/py/docs/source/api.rst @@ -1,24 +1,52 @@ +.. + this file was auto-generated by `generate_api_module_listing.py` + DO NOT EDIT + :orphan: ====================== Selenium Documentation ====================== -Common +common ------ .. currentmodule:: selenium.common .. autosummary:: - :toctree: common + :toctree: selenium_common selenium.common.exceptions -Webdriver.common +webdriver.chrome +---------------- + +.. currentmodule:: selenium.webdriver.chrome +.. autosummary:: + :toctree: selenium_webdriver_chrome + + selenium.webdriver.chrome.options + selenium.webdriver.chrome.remote_connection + selenium.webdriver.chrome.service + selenium.webdriver.chrome.webdriver + +webdriver.chromium +------------------ + +.. currentmodule:: selenium.webdriver.chromium +.. autosummary:: + :toctree: selenium_webdriver_chromium + + selenium.webdriver.chromium.options + selenium.webdriver.chromium.remote_connection + selenium.webdriver.chromium.service + selenium.webdriver.chromium.webdriver + +webdriver.common ---------------- .. currentmodule:: selenium.webdriver.common .. autosummary:: - :toctree: webdriver + :toctree: selenium_webdriver_common selenium.webdriver.common.action_chains selenium.webdriver.common.actions.action_builder @@ -60,65 +88,71 @@ Webdriver.common selenium.webdriver.common.virtual_authenticator selenium.webdriver.common.window -Webdriver.support ------------------ +webdriver.common.actions +------------------------ -.. currentmodule:: selenium.webdriver.support +.. currentmodule:: selenium.webdriver.common.actions .. autosummary:: - :toctree: webdriver_support + :toctree: selenium_webdriver_common_actions - selenium.webdriver.support.abstract_event_listener - selenium.webdriver.support.color - selenium.webdriver.support.event_firing_webdriver - selenium.webdriver.support.events - selenium.webdriver.support.expected_conditions - selenium.webdriver.support.relative_locator - selenium.webdriver.support.select - selenium.webdriver.support.ui - selenium.webdriver.support.wait + selenium.webdriver.common.actions.action_builder + selenium.webdriver.common.actions.input_device + selenium.webdriver.common.actions.interaction + selenium.webdriver.common.actions.key_actions + selenium.webdriver.common.actions.key_input + selenium.webdriver.common.actions.mouse_button + selenium.webdriver.common.actions.pointer_actions + selenium.webdriver.common.actions.pointer_input + selenium.webdriver.common.actions.wheel_actions + selenium.webdriver.common.actions.wheel_input -Webdriver.chrome ----------------- +webdriver.common.bidi +--------------------- -.. currentmodule:: selenium.webdriver.chrome +.. currentmodule:: selenium.webdriver.common.bidi .. autosummary:: - :toctree: webdriver_chrome + :toctree: selenium_webdriver_common_bidi - selenium.webdriver.chrome.options - selenium.webdriver.chrome.remote_connection - selenium.webdriver.chrome.service - selenium.webdriver.chrome.webdriver + selenium.webdriver.common.bidi.browser + selenium.webdriver.common.bidi.browsing_context + selenium.webdriver.common.bidi.cdp + selenium.webdriver.common.bidi.common + selenium.webdriver.common.bidi.console + selenium.webdriver.common.bidi.log + selenium.webdriver.common.bidi.network + selenium.webdriver.common.bidi.script + selenium.webdriver.common.bidi.session + selenium.webdriver.common.bidi.storage + selenium.webdriver.common.bidi.webextension -Webdriver.chromium ------------------- +webdriver.common.fedcm +---------------------- -.. currentmodule:: selenium.webdriver.chromium +.. currentmodule:: selenium.webdriver.common.fedcm .. autosummary:: - :toctree: webdriver_chromium + :toctree: selenium_webdriver_common_fedcm - selenium.webdriver.chromium.options - selenium.webdriver.chromium.remote_connection - selenium.webdriver.chromium.service - selenium.webdriver.chromium.webdriver + selenium.webdriver.common.fedcm.account + selenium.webdriver.common.fedcm.dialog -Webdriver.edge +webdriver.edge -------------- .. currentmodule:: selenium.webdriver.edge .. autosummary:: - :toctree: webdriver_edge + :toctree: selenium_webdriver_edge selenium.webdriver.edge.options selenium.webdriver.edge.remote_connection selenium.webdriver.edge.service selenium.webdriver.edge.webdriver -Webdriver.firefox +webdriver.firefox ----------------- .. currentmodule:: selenium.webdriver.firefox .. autosummary:: - :toctree: webdriver_firefox + :toctree: selenium_webdriver_firefox selenium.webdriver.firefox.firefox_binary selenium.webdriver.firefox.firefox_profile @@ -127,23 +161,23 @@ Webdriver.firefox selenium.webdriver.firefox.service selenium.webdriver.firefox.webdriver -Webdriver.ie +webdriver.ie ------------ .. currentmodule:: selenium.webdriver.ie .. autosummary:: - :toctree: webdriver_ie + :toctree: selenium_webdriver_ie selenium.webdriver.ie.options selenium.webdriver.ie.service selenium.webdriver.ie.webdriver -Webdriver.remote +webdriver.remote ---------------- .. currentmodule:: selenium.webdriver.remote .. autosummary:: - :toctree: webdriver_remote + :toctree: selenium_webdriver_remote selenium.webdriver.remote.bidi_connection selenium.webdriver.remote.client_config @@ -163,40 +197,57 @@ Webdriver.remote selenium.webdriver.remote.webelement selenium.webdriver.remote.websocket_connection -Webdriver.safari +webdriver.safari ---------------- .. currentmodule:: selenium.webdriver.safari .. autosummary:: - :toctree: webdriver_safari + :toctree: selenium_webdriver_safari + + selenium.webdriver.safari.options + selenium.webdriver.safari.permissions + selenium.webdriver.safari.remote_connection + selenium.webdriver.safari.service + selenium.webdriver.safari.webdriver + +webdriver.support +----------------- + +.. currentmodule:: selenium.webdriver.support +.. autosummary:: + :toctree: selenium_webdriver_support - selenium.webdriver.safari.options - selenium.webdriver.safari.permissions - selenium.webdriver.safari.remote_connection - selenium.webdriver.safari.service - selenium.webdriver.safari.webdriver + selenium.webdriver.support.abstract_event_listener + selenium.webdriver.support.color + selenium.webdriver.support.event_firing_webdriver + selenium.webdriver.support.events + selenium.webdriver.support.expected_conditions + selenium.webdriver.support.relative_locator + selenium.webdriver.support.select + selenium.webdriver.support.ui + selenium.webdriver.support.wait -Webdriver.webkitgtk +webdriver.webkitgtk ------------------- .. currentmodule:: selenium.webdriver.webkitgtk .. autosummary:: - :toctree: webdriver_webkitgtk + :toctree: selenium_webdriver_webkitgtk - selenium.webdriver.webkitgtk.options - selenium.webdriver.webkitgtk.service - selenium.webdriver.webkitgtk.webdriver + selenium.webdriver.webkitgtk.options + selenium.webdriver.webkitgtk.service + selenium.webdriver.webkitgtk.webdriver -Webdriver.wpewebkit +webdriver.wpewebkit ------------------- .. currentmodule:: selenium.webdriver.wpewebkit .. autosummary:: - :toctree: webdriver_wpewebkit + :toctree: selenium_webdriver_wpewebkit - selenium.webdriver.wpewebkit.options - selenium.webdriver.wpewebkit.service - selenium.webdriver.wpewebkit.webdriver + selenium.webdriver.wpewebkit.options + selenium.webdriver.wpewebkit.service + selenium.webdriver.wpewebkit.webdriver Indices and tables diff --git a/py/generate_api_module_listing.py b/py/generate_api_module_listing.py new file mode 100644 index 0000000000000..b2168545bda3d --- /dev/null +++ b/py/generate_api_module_listing.py @@ -0,0 +1,94 @@ +# Licensed to the Software Freedom Conservancy (SFC) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The SFC licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +# ----------------------------------------------------------------- +# This script recursively scans the `selenium` package directory +# to find all modules, then generates the `py/docs/source/api.rst` +# file containing a listing of all modules in separate sections. +# The `api.rst` file is later used by `sphinx-autogen` to generate +# sphinx autodoc stub pages used in the Python API documentation. +# See `py/tox.ini` for how it is invoked. + +import os +import site + + +def find_modules(package_name): + modules = [] + for dirpath, _, filenames in os.walk(package_name): + for filename in filenames: + if filename.endswith(".py") and not filename.startswith("__"): + module_name = ( + os.path.join(dirpath, filename) + .removeprefix(site.getsitepackages()[-1]) + .removeprefix(os.sep) + .removesuffix(".py") + .replace(os.sep, ".") + ) + modules.append(module_name) + return sorted(set(modules)) + + +if __name__ == "__main__": + package_name = "selenium" + output_file = os.path.join("docs", "source", "api.rst") + print(f"generating module list for sphinx autodoc in: {output_file}\n") + modules = find_modules(package_name) + base_modules = [mod for mod in sorted(set(module.rsplit(".", 1)[0] for module in modules)) if mod != package_name] + print("found sections:") + for base_module in base_modules: + print(f" {base_module}") + with open(output_file, "w") as f: + f.write( + """\ +.. + this file was auto-generated by `generate_api_module_listing.py` + DO NOT EDIT + +:orphan: + +====================== +Selenium Documentation +====================== +""" + ) + for base_module in base_modules: + content_section = base_module.split(".", 1)[1] + separator = "-" * len(content_section) + f.write( + f""" +{content_section} +{separator} + +.. currentmodule:: {base_module} +.. autosummary:: + :toctree: {base_module.replace(".", "_")} + +""" + ) + for module in modules: + if base_module in module: + f.write(f" {module}\n") + f.write( + """ +Indices and tables + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` +""" + ) diff --git a/py/tox.ini b/py/tox.ini index 35fb51f8f5535..ba4895423f8b0 100644 --- a/py/tox.ini +++ b/py/tox.ini @@ -15,6 +15,8 @@ deps = -r {toxinidir}/docs/requirements.txt -r {toxinidir}/requirements.txt commands = + ; generate `docs/source/api.rst` with module listing + {envpython} ./generate_api_module_listing.py ; regenerate autodoc stub pages sphinx-autogen docs/source/api.rst ; build api docs