Fix warnings and issues in docs (#825)

* Fix warnings and issues in docs

Signed-off-by: Aleksander Kantak <aleksander.kantak@intel.com>

* fixup! Fix warnings and issues in docs

Signed-off-by: Aleksander Kantak <aleksander.kantak@intel.com>

---------

Signed-off-by: Aleksander Kantak <aleksander.kantak@intel.com>

docs/advanced_topics.rst

@@ -49,6 +49,7 @@ Advanced Topics
    multiple_plans
    compression_settings
    overriding_agg_fn
+   straggler_handling_algorithms
    log_metric_callback
    supported_aggregation_algorithms
    overriding_plan_settings

docs/experimental_features.rst

@@ -3,9 +3,9 @@
 
 .. _experimental_features:
 
-***************
+*********************
 Experimental Features
-***************
+*********************
 
 This section includes a set of experimental features that our team wants feedback on before adding them into core |productName|. 
 Experimental features are *not* ready for production. These features are under active development and intended to make their way into core |productName|, but there are several key considerations to make when building on top of these:

docs/log_metric_callback.rst

@@ -39,8 +39,8 @@ You could also add your custom metric logging function by defining the function
         your code 
 
 
-Example of a Metric Callback
-============================
+Example of MLFlow's Metric Callback
+=====================================
 
 This example shows how to use MLFlow logger to log metrics:
 
@@ -104,8 +104,8 @@ Follow the steps below to write your custom callback function instead. As an exa
         template : src.mnist_utils.callback_name
 
 
-Example of a Metric Callback
-============================
+Example of TensorBoard's Metric Callback
+==========================================
 
 The following is an example of a log metric callback, which writes metric values to the TensorBoard.
 

docs/mermaid/CSR_signing.mmd

@@ -4,7 +4,7 @@ Title: Collaborator Certificate Signing Flow
   participant AC as Alice's Collaborator Node
   participant B as Bob
   participant BG as Bob's Certificate Signing System
-  A->>AC: Alice runs<br>`fx collaborator generate-cert-request`<br>to create .key and .csr file<br>
+  A->>AC: Alice runs<br>`fx collaborator generate-cert-request`<br>to create .key and .csr file
   AC->>A: PKI script outputs a hash to the screen
   A->>B: Alice sends the .csr to Bob
   B->>BG: Bob moves the .csr<br/> to the signing system with<br>`fx collaborator certify --request-pkg`

docs/overriding_agg_fn.rst

@@ -291,7 +291,7 @@ This is an example of a custom tensor clipping aggregation function that multipl
 A full implementation can be found at `Federated_Pytorch_MNIST_custom_aggregation_Tutorial.ipynb <https://github.com/intel/openfl/blob/develop/openfl-tutorials/Federated_Pytorch_MNIST_custom_aggregation_Tutorial.ipynb>`_
 
 Example of a Privileged Aggregation Function
-========================================
+============================================
 
 Most of the time the AggregationFunction interface is sufficient to implement custom methods, but in certain scenarios users may want to store additional information inside the TensorDB Dataframe beyond the aggregated tensor. The :class:`openfl.interface.aggregation_functions.experimental.PrivilegedAggregationFunction` interface is provided for this use, and gives the user direct access to aggregator's TensorDB dataframe (notice the `tensor_db` param in the call function replaces the `db_iterator` from the standard AggregationFunction interface). As the name suggests, this interface is called privileged because with great power comes great responsibility, and modifying the TensorDB dataframe directly can lead to unexpected behavior and experiment failures if entries are arbitrarily deleted.
 

docs/running_the_federation.rst

@@ -71,7 +71,7 @@ The *Director manager* sets up the *Director*, which is the central node of the
 
 .. _plan_agreement_director:
 
-OPTIONAL STEP: Plan Agreement
+OPTIONAL STEP: Director's Plan Agreement
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In order to carry out a secure federation, the Director must approve the FL Plan before starting the experiment. This check could be enforced with the use of the setting :code:`review_experiment: True` in director config. Refer to **director_config_review_exp.yaml** file under **PyTorch_Histology** interactive API example.
 After the Director approves the experiment, it starts the aggregator and sends the experiment archive to all the participanting Envoys for review.
@@ -143,7 +143,7 @@ The *Collaborator manager* sets up the *Envoys*, which are long-lived components
 
 .. _plan_agreement_envoy:
 
-OPTIONAL STEP: Plan Agreement
+OPTIONAL STEP: Envoy's Plan Agreement
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In order to carry out a secure federation, each of the Envoys must approve the experiment before it is started, after the Director's approval. This check could be enforced with the use of the parameter :code:`review_experiment: True` in envoy config. Refer to **envoy_config_review_exp.yaml** file under **PyTorch_Histology** interactive API example.
 If any of the Envoys rejects the experiment, a :code:`set_experiment_failed` request is sent to the Director to stop the aggregator.
@@ -785,14 +785,14 @@ Bare Metal Approach
     See :ref:`install_package` for details.
 
 
-You can use the `"Hello Federation" bash script <https://github.com/intel/openfl/blob/develop/tests/github/test_hello_federation.sh>`_ to quickly create a federation (an aggregator node and two collaborator nodes) to test the project pipeline.
+You can use the `"Hello Federation" python script <https://github.com/intel/openfl/blob/develop/tests/github/test_hello_federation.py>`_ to quickly create a federation (an aggregator node and two collaborator nodes) to test the project pipeline.
 
-.. literalinclude:: ../tests/github/test_hello_federation.sh
-  :language: bash
+.. literalinclude:: ../tests/github/test_hello_federation.py
+  :language: python
 
 However, continue with the following procedure for details in creating a federation with an aggregator-based workflow.
 
-    `STEP 1: Create a Workspace on the Aggregator`_
+    `STEP 1: Create a Workspace`_
 
         - Creates a federated learning workspace on one of the nodes.
 
@@ -1198,7 +1198,7 @@ Option 2: Deploy Your Workspace in a Docker Container
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. note::
-    You have to set up a TaskRunner and run :code:`fx plan initialize` in the workspace directory. See `STEP 1: Create a Workspace on the Aggregator`_ for details.
+    You have to set up a TaskRunner and run :code:`fx plan initialize` in the workspace directory. See `STEP 1: Create a Workspace`_ for details.
 
 
 1. Build an image with the workspace you created.

docs/workflow_interface.rst

@@ -3,9 +3,9 @@
 
 .. _workflow_interface:
 
-***************
+******************
 Workflow Interface
-***************
+******************
 
 **Important Note**
 
@@ -14,7 +14,7 @@ The OpenFL workflow interface is experimental, subject to change, and is current
 What is it?
 ===========
 
-A new OpenFL interface that gives significantly more flexility to researchers in the construction of federated learning experiments. It is heavily influenced by the interface and design of `Metaflow , the popular framework for data scientists originally developed at Netflix. There are several reasons we converged on Metaflow as inspiration for our work:
+A new OpenFL interface that gives significantly more flexility to researchers in the construction of federated learning experiments. It is heavily influenced by the interface and design of `Metaflow` , the popular framework for data scientists originally developed at Netflix. There are several reasons we converged on Metaflow as inspiration for our work:
 
 1. Clean expression of task sequence. Flows start with a `start` task, and end with `end`. The next task in the sequence is called by `self.next`.
 2. Easy selection of what should be sent between tasks using `include` or `exclude`