diff --git a/datasets/dev/build-flwr-datasets-docs.sh b/datasets/dev/build-flwr-datasets-docs.sh index dc3cd979d5c8..aefa47f147f8 100755 --- a/datasets/dev/build-flwr-datasets-docs.sh +++ b/datasets/dev/build-flwr-datasets-docs.sh @@ -28,3 +28,6 @@ fi # Note if a package cannot be reach via the recursive traversal, even if it has __all__, it won't be documented. echo "Generating the docs based on only the functionality given in the __all__." sphinx-build -M html source build + +# Remove the autogenerated source files after the build +rm source/ref-api/*.rst diff --git a/doc/build-versioned-docs.sh b/doc/build-versioned-docs.sh index 0d7185b5e470..b61472d216e9 100755 --- a/doc/build-versioned-docs.sh +++ b/doc/build-versioned-docs.sh @@ -76,6 +76,9 @@ END # Restore branch as it was to avoid conflicts git restore source/_templates + git restore source/_templates/autosummary || rm -rf source/_templates/autosummary + rm source/ref-api/*.rst + if [ "$current_version" = "v1.5.0" ]; then git restore source/conf.py fi @@ -100,6 +103,7 @@ for current_language in ${languages}; do export current_language sphinx-build -b html source/ build/html/${current_version}/${current_language} -A lang=True -D language=${current_language} done +rm source/ref-api/*.rst # Copy main version to the root of the built docs cp -r build/html/main/en/* build/html/ diff --git a/doc/source/_templates/autosummary/base.rst b/doc/source/_templates/autosummary/base.rst new file mode 100644 index 000000000000..5536fa10863f --- /dev/null +++ b/doc/source/_templates/autosummary/base.rst @@ -0,0 +1,5 @@ +{{ name | escape | underline}} + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ objname }} diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst new file mode 100644 index 000000000000..b4b35789bc6f --- /dev/null +++ b/doc/source/_templates/autosummary/class.rst @@ -0,0 +1,33 @@ +{{ name | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :show-inheritance: + :inherited-members: + + {% block methods %} + + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {% for item in methods %} + {% if item != "__init__" %} + ~{{ name }}.{{ item }} + {% endif %} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/doc/source/_templates/autosummary/module.rst b/doc/source/_templates/autosummary/module.rst new file mode 100644 index 000000000000..571db198d27c --- /dev/null +++ b/doc/source/_templates/autosummary/module.rst @@ -0,0 +1,66 @@ +{{ name | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: Module Attributes + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + :toctree: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :toctree: + :template: autosummary/class.rst + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :toctree: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :template: autosummary/module.rst + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py index 8f68c992a314..503f76cb9eca 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -96,6 +96,7 @@ extensions = [ "sphinx.ext.napoleon", "sphinx.ext.autodoc", + "sphinx.ext.autosummary", "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinx.ext.graphviz", @@ -109,6 +110,42 @@ "nbsphinx", ] +# Generate .rst files +autosummary_generate = True + +# Document ONLY the objects from __all__ (present in __init__ files). +# It will be done recursively starting from flwr.__init__ +# Starting point is controlled in the index.rst file. +autosummary_ignore_module_all = False + +# Each class and function docs start with the path to it +# Make the flwr_datasets.federated_dataset.FederatedDataset appear as FederatedDataset +# The full name is still at the top of the page +add_module_names = False + +def find_test_modules(package_path): + """Go through the python files and exclude every *_test.py file.""" + full_path_modules = [] + for root, dirs, files in os.walk(package_path): + for file in files: + if file.endswith('_test.py'): + # Construct the module path relative to the package directory + full_path = os.path.join(root, file) + relative_path = os.path.relpath(full_path, package_path) + # Convert file path to dotted module path + module_path = os.path.splitext(relative_path)[0].replace(os.sep, '.') + full_path_modules.append(module_path) + modules = [] + for full_path_module in full_path_modules: + parts = full_path_module.split('.') + for i in range(len(parts)): + modules.append('.'.join(parts[i:])) + return modules + +# Stop from documenting the *_test.py files. +# That's the only way to do that in autosummary (make the modules as mock_imports). +autodoc_mock_imports = find_test_modules(os.path.abspath("../../src/py/flwr")) + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -174,7 +211,8 @@ "evaluation": "explanation-federated-evaluation.html", "differential-privacy-wrappers": "explanation-differential-privacy.html", # Restructuring: references - "apiref-flwr": "ref-api-flwr.html", + "apiref-flwr": "ref-api/flwr.html", + "ref-api-flwr": "ref-api/flwr.html", "apiref-cli": "ref-api-cli.html", "examples": "ref-example-projects.html", "telemetry": "ref-telemetry.html", diff --git a/doc/source/index.rst b/doc/source/index.rst index c4a313414d3a..9b4b5b195fbb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -119,11 +119,17 @@ References Information-oriented API reference and other reference material. +.. autosummary:: + :toctree: ref-api + :template: autosummary/module.rst + :caption: API reference + :recursive: + + flwr + .. toctree:: :maxdepth: 2 - :caption: API reference - ref-api-flwr ref-api-cli .. toctree:: diff --git a/doc/source/ref-api-flwr.rst b/doc/source/ref-api-flwr.rst deleted file mode 100644 index e1983cd92c90..000000000000 --- a/doc/source/ref-api-flwr.rst +++ /dev/null @@ -1,265 +0,0 @@ -flwr (Python API reference) -=========================== - - -.. _flwr-client-apiref: - -client ------- - -.. automodule:: flwr.client - -.. _flwr-client-Client-apiref: - -Client -~~~~~~ - -.. autoclass:: flwr.client.Client - :members: - - -.. _flwr-client-start_client-apiref: - -start_client -~~~~~~~~~~~~ - -.. autofunction:: flwr.client.start_client - - -.. _flwr-client-NumPyClient-apiref: - -NumPyClient -~~~~~~~~~~~ - -.. autoclass:: flwr.client.NumPyClient - :members: - - -.. _flwr-client-start_numpy_client-apiref: - -start_numpy_client -~~~~~~~~~~~~~~~~~~ - -.. autofunction:: flwr.client.start_numpy_client - - -.. _flwr-simulation-start_simulation-apiref: - -start_simulation -~~~~~~~~~~~~~~~~~~ - -.. autofunction:: flwr.simulation.start_simulation - - -.. _flwr-server-apiref: - -server ------- - -.. automodule:: flwr.server - - -.. _flwr-server-start_server-apiref: - -server.start_server -~~~~~~~~~~~~~~~~~~~ - -.. autofunction:: flwr.server.start_server - - -.. _flwr-server-strategy-apiref: - -server.strategy -~~~~~~~~~~~~~~~ - -.. automodule:: flwr.server.strategy - - -.. _flwr-server-strategy-Strategy-apiref: - -server.strategy.Strategy -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.Strategy - :members: - - -.. _flwr-server-strategy-FedAvg-apiref: - -server.strategy.FedAvg -^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedAvg - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedAvgM-apiref: - -server.strategy.FedAvgM -^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedAvgM - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedMedian-apiref: - -server.strategy.FedMedian -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedMedian - :members: - - .. automethod:: __init__ - -.. _flwr-server-strategy-QFedAvg-apiref: - -server.strategy.QFedAvg -^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.QFedAvg - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FaultTolerantFedAvg-apiref: - -server.strategy.FaultTolerantFedAvg -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FaultTolerantFedAvg - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedOpt-apiref: - -server.strategy.FedOpt -^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedOpt - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedProx-apiref: - -server.strategy.FedProx -^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedProx - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedAdagrad-apiref: - -server.strategy.FedAdagrad -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedAdagrad - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedAdam-apiref: - -server.strategy.FedAdam -^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedAdam - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedYogi-apiref: - -server.strategy.FedYogi -^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedYogi - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedTrimmedAvg-apiref: - -server.strategy.FedTrimmedAvg -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedTrimmedAvg - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-Krum-apiref: - -server.strategy.Krum -^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.Krum - :members: - - .. automethod:: __init__ - -.. _flwr-server-strategy-Bulyan-apiref: - -server.strategy.Bulyan -^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.Bulyan - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-FedXgbNnAvg-apiref: - -server.strategy.FedXgbNnAvg -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.FedXgbNnAvg - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-DPFedAvgAdaptive-apiref: - -server.strategy.DPFedAvgAdaptive -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.DPFedAvgAdaptive - :members: - - .. automethod:: __init__ - - -.. _flwr-server-strategy-DPFedAvgFixed-apiref: - -server.strategy.DPFedAvgFixed -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autoclass:: flwr.server.strategy.DPFedAvgFixed - :members: - - .. automethod:: __init__ - -common ------- - -.. automodule:: flwr.common - :members: - :exclude-members: event