Makes various improvements to the docs (#1444)

* Fix various issues with the docs
* Improve doc rendering for strategies

doc/source/_static/custom.css

@@ -1,5 +1,7 @@
-@import url(https://fonts.googleapis.com/css?family=Inter:400,600);
-
 html, body{
-    font-family: Inter,BlinkMacSystemFont,-apple-system,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,Helvetica,Arial,sans-serif;
+    font-family: Montserrat,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,Noto Sans,sans-serif,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji;
+}
+
+.mermaid {
+    background: #f8f8f8
 }

doc/source/_templates/base.html

@@ -85,6 +85,8 @@
     {%- block scripts -%}
 
     {# Custom JS #}
+    <script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
+
     {%- block regular_scripts -%}
     {% for path in script_files -%}
       {{ js_tag(path) }}

doc/source/conf.py

@@ -24,7 +24,7 @@
 
 
 # Fixing path issue for autodoc
-sys.path.insert(0, os.path.abspath('../../src/py'))
+sys.path.insert(0, os.path.abspath("../../src/py"))
 
 
 # -- Project information -----------------------------------------------------
@@ -135,3 +135,11 @@
 """
 nbsphinx_prolog = _open_in_colab_button
 nbsphinx_epilog = _open_in_colab_button
+
+# -- Options for sphinxcontrib-mermaid -------------------------------------
+# Don't load it automatically through the extension as we are loading it through the
+# theme (see base.html) as the inclusion of require.js by the extension `nbsphinx`
+# breaks the way mermaid is loaded. The solution is to load mermaid before the
+# require.js script added by `nbsphinx`. We can only enforce this in the theme
+# itself.
+mermaid_version = ""

doc/source/contributor-setup.rst

@@ -32,7 +32,7 @@ Install a ``flwr`` pre-release from PyPI:
 - ``pip install -U --pre flwr`` (without extras)
 - ``pip install -U --pre flwr[simulation]`` (with extras)
 
-Python packages can be installed from git repositories. Use the following command to install the latest version of Flower directly from GitHub::
+Python packages can be installed from git repositories. Use one of the following commands to install the Flower directly from GitHub.
 
 Install ``flwr`` from the default GitHub branch (``main``):
 

doc/source/secagg.rst

@@ -66,94 +66,95 @@ In this implementation, each client will be assigned with a unique index (int) f
 The Flower server will execute and process received results in the following order:
 
 .. mermaid::
-  sequenceDiagram
-      participant S as Flower Server
-      participant P as SecAgg+ Protocol
-      participant C1 as Flower Client
-      participant C2 as Flower Client
-      participant C3 as Flower Client
-
-      S->>P: generate_graph
-      activate P
-      P-->>S: client_graph
-      deactivate P
-
-      Note left of P: Stage 0:<br/>Setup Config
-      rect rgb(249, 219, 130)
-      S->>P: setup_config<br/>clients, config_dict
-      activate P
-      P->>C1: SetupConfigIns
-      deactivate P
-      P->>C2:
-      P->>C3:
-      C1->>P: SetupConfigRes (empty)
-      C2->>P:
-      C3->>P:
-      activate P
-      P-->>S: None
-      deactivate P
-      end
-
-      Note left of P: Stage 1:<br/>Ask Keys
-      rect rgb(249, 219, 130)
-      S->>P: ask_keys<br/>clients
-      activate P
-      P->>C1: AskKeysIns (empty)
-      deactivate P
-      P->>C2:
-      P->>C3:
-      C1->>P: AskKeysRes
-      C2->>P:
-      C3->>P:
-      activate P
-      P-->>S: public keys
-      deactivate P
-      end
-
-      Note left of P: Stage 2:<br/>Share Keys
-      rect rgb(249, 219, 130)
-      S->>P: share_keys<br/>clients, public_keys_dict,<br/>client_graph
-      activate P
-      P->>C1: ShareKeysIns
-      deactivate P
-      P->>C2:
-      P->>C3:
-      C1->>P: ShareKeysRes
-      C2->>P:
-      C3->>P:
-      activate P
-      P-->>S: encryted key shares
-      deactivate P
-      end
-
-      Note left of P: Stage 3:<br/>Ask Vectors
-      rect rgb(249, 219, 130)
-      S->>P: ask_vectors<br/>clients,<br/>forward_packet_list_dict
-      activate P
-      P->>C1: AskVectorsIns
-      deactivate P
-      P->>C2:
-      P->>C3:
-      C1->>P: AskVectorsRes
-      C2->>P:
-      activate P
-      P-->>S: masked vectors
-      deactivate P
-      end
-
-      Note left of P: Stage 4:<br/>Unmask Vectors
-      rect rgb(249, 219, 130)
-      S->>P: unmask_vectors<br/>clients, dropped_clients,<br/>client_graph
-      activate P
-      P->>C1: UnmaskVectorsIns
-      deactivate P
-      P->>C2:
-      C1->>P: UnmaskVectorsRes
-      C2->>P:
-      activate P
-      P-->>S: key shares
-      deactivate P
-      end
+
+    sequenceDiagram
+        participant S as Flower Server
+        participant P as SecAgg+ Protocol
+        participant C1 as Flower Client
+        participant C2 as Flower Client
+        participant C3 as Flower Client
+
+        S->>P: generate_graph
+        activate P
+        P-->>S: client_graph
+        deactivate P
+
+        Note left of P: Stage 0:<br/>Setup Config
+        rect rgb(249, 219, 130)
+        S->>P: setup_config<br/>clients, config_dict
+        activate P
+        P->>C1: SetupConfigIns
+        deactivate P
+        P->>C2:
+        P->>C3:
+        C1->>P: SetupConfigRes (empty)
+        C2->>P:
+        C3->>P:
+        activate P
+        P-->>S: None
+        deactivate P
+        end
+
+        Note left of P: Stage 1:<br/>Ask Keys
+        rect rgb(249, 219, 130)
+        S->>P: ask_keys<br/>clients
+        activate P
+        P->>C1: AskKeysIns (empty)
+        deactivate P
+        P->>C2:
+        P->>C3:
+        C1->>P: AskKeysRes
+        C2->>P:
+        C3->>P:
+        activate P
+        P-->>S: public keys
+        deactivate P
+        end
+
+        Note left of P: Stage 2:<br/>Share Keys
+        rect rgb(249, 219, 130)
+        S->>P: share_keys<br/>clients, public_keys_dict,<br/>client_graph
+        activate P
+        P->>C1: ShareKeysIns
+        deactivate P
+        P->>C2:
+        P->>C3:
+        C1->>P: ShareKeysRes
+        C2->>P:
+        C3->>P:
+        activate P
+        P-->>S: encryted key shares
+        deactivate P
+        end
+
+        Note left of P: Stage 3:<br/>Ask Vectors
+        rect rgb(249, 219, 130)
+        S->>P: ask_vectors<br/>clients,<br/>forward_packet_list_dict
+        activate P
+        P->>C1: AskVectorsIns
+        deactivate P
+        P->>C2:
+        P->>C3:
+        C1->>P: AskVectorsRes
+        C2->>P:
+        activate P
+        P-->>S: masked vectors
+        deactivate P
+        end
+
+        Note left of P: Stage 4:<br/>Unmask Vectors
+        rect rgb(249, 219, 130)
+        S->>P: unmask_vectors<br/>clients, dropped_clients,<br/>client_graph
+        activate P
+        P->>C1: UnmaskVectorsIns
+        deactivate P
+        P->>C2:
+        C1->>P: UnmaskVectorsRes
+        C2->>P:
+        activate P
+        P-->>S: key shares
+        deactivate P
+        end
 
 
 The :code:`LightSecAgg` abstraction
@@ -199,73 +200,74 @@ In this implementation, each client will be assigned with a unique index (int) f
 The Flower server will execute and process received results in the following order:
 
 .. mermaid::
-  sequenceDiagram
-      participant S as Flower Server
-      participant P as LightSecAgg Protocol
-      participant C1 as Flower Client
-      participant C2 as Flower Client
-      participant C3 as Flower Client
-
-      Note left of P: Stage 0:<br/>Setup Config
-      rect rgb(249, 219, 130)
-      S->>P: setup_config<br/>clients, config_dict
-      activate P
-      P->>C1: LightSecAggSetupConfigIns
-      deactivate P
-      P->>C2:
-      P->>C3:
-      C1->>P: LightSecAggSetupConfigRes
-      C2->>P:
-      C3->>P:
-      activate P
-      P-->>S: public keys
-      deactivate P
-      end
-
-      Note left of P: Stage 1:<br/>Ask Encrypted Encoded Masks
-      rect rgb(249, 219, 130)
-      S->>P: ask_encrypted_encoded_masks<br/>clients, public_keys_dict
-      activate P
-      P->>C1: AskEncryptedEncodedMasksIns
-      deactivate P
-      P->>C2:
-      P->>C3:
-      C1->>P: AskEncryptedEncodedMasksRes
-      C2->>P:
-      C3->>P:
-      activate P
-      P-->>S: forward packets
-      deactivate P
-      end
-
-      Note left of P: Stage 2:<br/>Ask Masked Models
-      rect rgb(249, 219, 130)
-      S->>P: share_keys<br/>clients, forward_packet_list_dict
-      activate P
-      P->>C1: AskMaskedModelsIns
-      deactivate P
-      P->>C2:
-      P->>C3:
-      C1->>P: AskMaskedModelsRes
-      C2->>P:
-      activate P
-      P-->>S: masked local models
-      deactivate P
-      end
-
-      Note left of P: Stage 3:<br/>Ask Aggregated Encoded Masks
-      rect rgb(249, 219, 130)
-      S->>P: ask_aggregated_encoded_masks<br/>clients
-      activate P
-      P->>C1: AskAggregatedEncodedMasksIns
-      deactivate P
-      P->>C2:
-      C1->>P: AskAggregatedEncodedMasksRes
-      C2->>P:
-      activate P
-      P-->>S: the aggregated model
-      deactivate P
-      end
+
+    sequenceDiagram
+        participant S as Flower Server
+        participant P as LightSecAgg Protocol
+        participant C1 as Flower Client
+        participant C2 as Flower Client
+        participant C3 as Flower Client
+
+        Note left of P: Stage 0:<br/>Setup Config
+        rect rgb(249, 219, 130)
+        S->>P: setup_config<br/>clients, config_dict
+        activate P
+        P->>C1: LightSecAggSetupConfigIns
+        deactivate P
+        P->>C2:
+        P->>C3:
+        C1->>P: LightSecAggSetupConfigRes
+        C2->>P:
+        C3->>P:
+        activate P
+        P-->>S: public keys
+        deactivate P
+        end
+
+        Note left of P: Stage 1:<br/>Ask Encrypted Encoded Masks
+        rect rgb(249, 219, 130)
+        S->>P: ask_encrypted_encoded_masks<br/>clients, public_keys_dict
+        activate P
+        P->>C1: AskEncryptedEncodedMasksIns
+        deactivate P
+        P->>C2:
+        P->>C3:
+        C1->>P: AskEncryptedEncodedMasksRes
+        C2->>P:
+        C3->>P:
+        activate P
+        P-->>S: forward packets
+        deactivate P
+        end
+
+        Note left of P: Stage 2:<br/>Ask Masked Models
+        rect rgb(249, 219, 130)
+        S->>P: share_keys<br/>clients, forward_packet_list_dict
+        activate P
+        P->>C1: AskMaskedModelsIns
+        deactivate P
+        P->>C2:
+        P->>C3:
+        C1->>P: AskMaskedModelsRes
+        C2->>P:
+        activate P
+        P-->>S: masked local models
+        deactivate P
+        end
+
+        Note left of P: Stage 3:<br/>Ask Aggregated Encoded Masks
+        rect rgb(249, 219, 130)
+        S->>P: ask_aggregated_encoded_masks<br/>clients
+        activate P
+        P->>C1: AskAggregatedEncodedMasksIns
+        deactivate P
+        P->>C2:
+        C1->>P: AskAggregatedEncodedMasksRes
+        C2->>P:
+        activate P
+        P-->>S: the aggregated model
+        deactivate P
+        end
 
 
 Types

src/py/flwr/server/app.py

@@ -71,7 +71,7 @@ def start_server(  # pylint: disable=too-many-arguments
         A server implementation, either `flwr.server.Server` or a subclass
         thereof. If no instance is provided, then `start_server` will create
         one.
-    config : ServerConfig (default: None)
+    config : Optional[ServerConfig] (default: None)
         Currently supported values are `num_rounds` (int, default: 1) and
         `round_timeout` in seconds (float, default: None).
     strategy : Optional[flwr.server.Strategy] (default: None).