[py] Improve generated HTML docs for Python API

py/BUILD.bazel

@@ -1387,7 +1387,7 @@ py_console_script_binary(
     script = "sphinx-build",
     deps = [
         ":selenium",
-        requirement("sphinx-material"),
+        requirement("pydata_sphinx_theme"),
     ],
 )
 

py/docs/README.rst

@@ -10,65 +10,9 @@ PyPI package.
 How to build docs
 =================
 
-One can build the Python documentation without doing a full bazel build. The
-following instructions will build the setup a virtual environment and installs tox,
-clones the selenium repo and then runs ``tox -c py/tox.ini -e docs``, building the
-Python documentation.
-
 .. code-block:: console
 
-    python3 -m venv venv
-    source venv/bin/activate
-    pip install tox
-    git clone git@github.com:SeleniumHQ/selenium.git
-    cd selenium/
-    # uncomment and switch to your development branch if needed 
-    #git switch -c feature-branch origin/feature-branch
-    tox -c py/tox.ini -e docs
-
-This works in a similar manner as the larger selenium bazel build, but does just the Python
-documentation portion.
-
-
-What is happening under the covers of tox, sphinx
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-tox is essentially a build tool for Python. Here it sets up its own virtual env and installs
-the documentation packages (sphinx and jinja2) as well as the required selenium python
-dependencies. Then tox runs the ``sphinx-autogen`` command to generate autodoc stub pages.
-Then it runs ``sphinx-build`` to build the HTML docs.
-
-Sphinx is .. well a much larger topic then what we could cover here. Most important to say
-here is that the docs are using the "sphinx-material" theme (AKA "Material for Sphinx" theme)
-and the the majority of the api documentation is autogenerated. There is plenty of information
-available and currently the documentation is fairly small and not complex. So some basic
-understanding of reStructuredText and the Sphinx tool chain should be sufficient to contribute
-and develop the Python docs.
-
-
-To clean up the build assets and tox cache
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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
-==========================
-
-We are working through the Sphinx build warnings and errors, trying to clean up both the syntax and
-the build.
-
-
-Contributing to Python docs
-===========================
-
-First it is recommended that you read the main `CONTRIBUTING.md <https://github.com/SeleniumHQ/selenium/blob/trunk/CONTRIBUTING.md>`_.
+    ./go py:docs_generate
 
-Some steps for contributing to the Python documentation ...
 
-- Check out changes locally using instructions above.
-- Try to resolve any warnings/errors.
-  - If too arduous, either ask for help or add to the list of known issues.
-- If this process is updated, please update this doc as well to help the next person.
+After building, docs are available in ``bazel-bin/py/docs/_build/html/``

py/docs/source/conf.py

@@ -36,13 +36,24 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "sphinx.ext.doctest",
-    "sphinx.ext.todo",
-    "sphinx.ext.coverage",
-    "sphinx.ext.imgmath",
+    "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
 ]
 
+# Extension configuration.
+autoclass_content = "both"
+autodoc_typehints = "description"
+autodoc_typehints_format = "short"
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "show-inheritance": True,
+    "undoc-members": True,
+    "inherited-members": True,
+}
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -90,28 +101,46 @@
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-# add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 # show_authors = False
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 
 
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages
-html_theme = "sphinx_material"
+html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "pygments_light_style": "tango",
+    "pygments_dark_style": "monokai",
+    "primary_sidebar_end": [],
+    "show_toc_level": 1,
+    "navbar_end": [
+        "theme-switcher",
+        "navbar-icon-links",
+    ],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/SeleniumHQ/selenium",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/selenium",
+            "icon": "fa-brands fa-python",
+        },
+    ],
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -146,7 +175,9 @@
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    "**": [],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -180,115 +211,3 @@
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = "Seleniumdoc"
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-# latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-# latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-    (
-        "index",
-        "Selenium.tex",
-        "Selenium Documentation",
-        "plightbo, simon.m.stewart, hbchai, jrhuggins, et al.",
-        "manual",
-    ),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-# latex_show_urls = False
-
-# Additional stuff for the LaTeX preamble.
-# latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_domain_indices = True
-
-
-# -- Options for manual page output --------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    ("index", "selenium", "Selenium Documentation", ["plightbo, simon.m.stewart, hbchai, jrhuggins, et al."], 1)
-]
-
-
-# -- Options for Epub output ---------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = "Selenium"
-epub_author = "The Selenium Project"
-epub_publisher = "The Selenium Project"
-epub_copyright = "2009-2024 Software Freedom Conservancy"
-
-# The language of the text. It defaults to the language option
-# or en if the language is not set.
-# epub_language = ''
-
-# The scheme of the identifier. Typical schemes are ISBN or URL.
-# epub_scheme = ''
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-# epub_identifier = ''
-
-# A unique identification for the text.
-# epub_uid = ''
-
-# HTML files that should be inserted before the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-# epub_pre_files = []
-
-# HTML files that should be inserted after the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-# epub_post_files = []
-
-# A list of files that should not be packed into the epub file.
-# epub_exclude_files = []
-
-# The depth of the table of contents in toc.ncx.
-# epub_tocdepth = 3
-
-# Allow duplicate toc entries.
-# epub_tocdup = True
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
-
-# 'members' includes anything that has a docstring, 'undoc-members' includes
-# functions without docstrings.
-autodoc_default_flags = ["members", "undoc-members"]
-
-# configuration for keeping the methods that can be invoked on said classes
-autodoc_default_options = {
-    "members": True,
-    "member-order": "bysource",
-    "undoc-members": True,
-    "inherited-members": True,
-}
-
-# Include __init__ comments
-autoclass_content = "both"

py/requirements.txt

@@ -7,13 +7,13 @@
 filetype~=1.2
 inflection~=0.5
 mypy~=2.1
+pydata-sphinx-theme~=0.19
 pytest~=9.0
 pytest-instafail~=0.5
 pytest-mock~=3.15
 pytest-trio~=0.8
 rich~=15.0
 Sphinx~=8.1
-sphinx-material~=0.0
 tox~=4.54
 trio-typing~=0.10
 twine~=6.2