1
# Licensed to the Software Freedom Conservancy (SFC) under one
2
# or more contributor license agreements.  See the NOTICE file
3
# distributed with this work for additional information
4
# regarding copyright ownership.  The SFC licenses this file
5
# to you under the Apache License, Version 2.0 (the
6
# "License"); you may not use this file except in compliance
7
# with the License.  You may obtain a copy of the License at
8
#
9
#   http://www.apache.org/licenses/LICENSE-2.0
10
#
11
# Unless required by applicable law or agreed to in writing,
12
# software distributed under the License is distributed on an
13
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
# KIND, either express or implied.  See the License for the
15
# specific language governing permissions and limitations
16
# under the License.
17

18

19
"""This script recursively scans the `selenium` package directory
20
to find all modules, then generates the `py/docs/source/api.rst`
21
file containing a listing of all modules in separate sections.
22
The `api.rst` file is later used by `sphinx-autogen` to generate
23
sphinx autodoc stub pages used in the Python API documentation.
24
See `py/tox.ini` for how it is invoked."""
25

26
import os
27
import site
28

29

30
def find_modules(package_name):
31
    modules = []
32
    for dirpath, _, filenames in os.walk(package_name):
33
        for filename in filenames:
34
            if filename.endswith(".py") and not filename.startswith("__"):
35
                module_name = (
36
                    os.path.join(dirpath, filename)
37
                    .removeprefix(site.getsitepackages()[-1])
38
                    .removeprefix(os.sep)
39
                    .removesuffix(".py")
40
                    .replace(os.sep, ".")
41
                )
42
                modules.append(module_name)
43
    return sorted(set(modules))
44

45

46
if __name__ == "__main__":
47
    package_name = "selenium"
48
    output_file = os.path.join("docs", "source", "api.rst")
49
    print(f"generating module list for sphinx autodoc in: {output_file}\n")
50
    modules = [module for module in find_modules(package_name) if ".devtools." not in module]
51
    base_modules = [mod for mod in sorted({module.rsplit(".", 1)[0] for module in modules}) if mod != package_name]
52
    print("found sections:")
53
    for base_module in base_modules:
54
        print(f"    {base_module}")
55
    with open(output_file, "w") as f:
56
        f.write(
57
            """\
58
..
59
    this file was auto-generated by `generate_api_module_listing.py`
60
    DO NOT EDIT
61

62
:orphan:
63

64
======================
65
Selenium Documentation
66
======================
67
"""
68
        )
69
        for base_module in base_modules:
70
            content_section = base_module.split(".", 1)[1]
71
            separator = "-" * len(content_section)
72
            f.write(
73
                f"""
74
{content_section}
75
{separator}
76

77
.. currentmodule:: {base_module}
78
.. autosummary::
79
   :toctree: {base_module.replace(".", "_")}
80

81
"""
82
            )
83
            for module in modules:
84
                if base_module in module:
85
                    if len(module.split(".")) - len(base_module.split(".")) == 1:
86
                        f.write(f"   {module}\n")
87
        f.write(
88
            """
89
Indices and tables
90

91
* :ref:`genindex`
92
* :ref:`modindex`
93
* :ref:`search`
94
"""
95
        )
96

97