Restructure docs

.github/workflows/docs.yml

@@ -19,6 +19,7 @@ jobs:
           python-version: 3.7.12
       - name: Install build tools
         run: |
+          sudo apt install pandoc
           python -m pip install -U pip==22.2
           python -m pip install -U setuptools==63.2.0
           python -m pip install -U poetry==1.1.14

doc/source/apiref-flwr.rst

@@ -6,12 +6,14 @@ API Reference - flwr
 
 client
 ------
+
 .. automodule:: flwr.client
 
 .. _flwr-client-Client-apiref:
 
 Client
 ~~~~~~
+
 .. autoclass:: flwr.client.Client
     :members:
 
@@ -20,13 +22,15 @@ Client
 
 start_client
 ~~~~~~~~~~~~
+
 .. autofunction:: flwr.client.start_client
 
 
 .. _flwr-client-NumPyClient-apiref:
 
 NumPyClient
 ~~~~~~~~~~~
+
 .. autoclass:: flwr.client.NumPyClient
     :members:
 
@@ -35,49 +39,56 @@ NumPyClient
 
 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:
 
@@ -87,7 +98,8 @@ server.strategy.FedAvg
 .. _flwr-server-strategy-FedAvgM-apiref:
 
 server.strategy.FedAvgM
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: flwr.server.strategy.FedAvgM
     :members:
 
@@ -97,7 +109,8 @@ server.strategy.FedAvgM
 .. _flwr-server-strategy-QFedAvg-apiref:
 
 server.strategy.QFedAvg
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: flwr.server.strategy.QFedAvg
     :members:
 
@@ -107,7 +120,8 @@ server.strategy.QFedAvg
 .. _flwr-server-strategy-FaultTolerantFedAvg-apiref:
 
 server.strategy.FaultTolerantFedAvg
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: flwr.server.strategy.FaultTolerantFedAvg
     :members:
 
@@ -117,7 +131,8 @@ server.strategy.FaultTolerantFedAvg
 .. _flwr-server-strategy-FedOpt-apiref:
 
 server.strategy.FedOpt
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: flwr.server.strategy.FedOpt
     :members:
 
@@ -127,7 +142,8 @@ server.strategy.FedOpt
 .. _flwr-server-strategy-FedAdagrad-apiref:
 
 server.strategy.FedAdagrad
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: flwr.server.strategy.FedAdagrad
     :members:
 
@@ -137,7 +153,8 @@ server.strategy.FedAdagrad
 .. _flwr-server-strategy-FedAdam-apiref:
 
 server.strategy.FedAdam
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: flwr.server.strategy.FedAdam
     :members:
 
@@ -147,13 +164,15 @@ server.strategy.FedAdam
 .. _flwr-server-strategy-FedYogi-apiref:
 
 server.strategy.FedYogi
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: flwr.server.strategy.FedYogi
     :members:
 
     .. automethod:: __init__
 
 common
 ------
+
 .. automodule:: flwr.common
   :members:

doc/source/conf.py

@@ -53,6 +53,7 @@
     "sphinx_design",
     "sphinxcontrib.mermaid",
     "sphinx_reredirects",
+    "nbsphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -119,3 +120,7 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
+
+# -- Options for HTML output -------------------------------------------------
+
+nbsphinx_execute = 'never'

doc/source/examples.rst

@@ -1,5 +1,5 @@
-Usage Examples
-==============
+Code examples
+=============
 
 Flower comes with a number of usage examples. The examples demonstrate how
 Flower can be used to federate different kinds of existing machine learning
@@ -9,7 +9,7 @@ pipelines, usually leveraging popular machine learning frameworks such as
 
 .. note::
    Flower usage examples used to be bundled with Flower in a package called
-   `flwr_example`. We are migrating those examples to standalone projects to
+   ``flwr_example``. We are migrating those examples to standalone projects to
    make them easier to use. All new examples are based in the directory
    `examples <https://github.com/adap/flower/tree/main/examples>`_.
 

doc/source/index.rst

@@ -16,37 +16,89 @@ The Flower Community is growing quickly - we're a friendly group of researchers,
     Join us on Slack
 
 
-User Guide
-----------
+Flower Framework
+----------------
 
 The user guide is targeted at researchers and developers who want to use Flower
 to bring existing machine learning workloads into a federated setting. One of
 Flower's design goals was to make this simple. Read on to learn more.
 
+Tutorials
+~~~~~~~~~
+
+A learning-oriented series of federated learning tutorials, the best place to start.
+
 .. toctree::
    :maxdepth: 1
+   :caption: Tutorial
+
+   tutorial/Flower-1-Intro-to-FL-PyTorch
+   tutorial/Flower-2-Strategies-in-FL-PyTorch
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Quickstart tutorials
+   :hidden:
 
-   installation
    quickstart-pytorch
    quickstart-tensorflow
    quickstart-huggingface
    quickstart-pytorch-lightning
    quickstart-mxnet
    quickstart-scikitlearn
-   evaluation
+
+QUICKSTART TUTORIALS: :ref:`PyTorch <quickstart-pytorch>` | :ref:`TensorFlow <quickstart-tensorflow>` | :ref:`🤗 Transformers <quickstart-huggingface>` | :ref:`PyTorch Lightning <quickstart-pytorch-lightning>` | :ref:`MXNet <quickstart-mxnet>` | :ref:`scikit-learn <quickstart-scikitlearn>`
+
+How-to guides
+~~~~~~~~~~~~~
+
+Problem-oriented how-to guides show step-by-step how to achieve a specific goal.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: How-to guides
+
+   installation
    configuring-clients
    strategies
    implementing-strategies
    saving-progress
    ssl-enabled-connections
-   examples
    example-walkthrough-pytorch-mnist
    example-pytorch-from-centralized-to-federated
    example-mxnet-walk-through
    example-jax-from-centralized-to-federated
    fedbn-example-pytorch-from-centralized-to-federated
    recommended-env-setup
    upgrade-to-flower-1.0
+
+Explanations
+~~~~~~~~~~~~
+
+Understanding-oriented concept guides explain and discuss key topics and underlying ideas behind Flower and collaborative AI.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Explanations
+
+   evaluation
+
+Reference
+~~~~~~~~~
+
+Information-oriented API reference and other reference material.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API reference
+
+   flwr <apiref-flwr>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference docs
+
+   examples
    changelog
    faq
 
@@ -58,20 +110,12 @@ Flower Baselines are a collection of organised scripts used to reproduce results
 
 .. toctree::
    :maxdepth: 1
+   :caption: Flower Baselines
 
    using-baselines
    contributing-baselines
 
 
-API Reference
--------------
-
-.. toctree::
-   :maxdepth: 3
-
-   flwr <apiref-flwr>
-
-
 Contributor Guide
 -----------------
 
@@ -80,6 +124,7 @@ intended to help along the way.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Contributor guide
 
    getting-started-for-contributors
    good-first-contributions

doc/source/quickstart-huggingface.rst

@@ -1,3 +1,6 @@
+.. _quickstart-huggingface:
+
+
 Quickstart 🤗 Transformers
 ==========================
 

doc/source/quickstart-mxnet.rst

@@ -1,3 +1,6 @@
+.. _quickstart-mxnet:
+
+
 Quickstart MXNet
 ================
 

doc/source/quickstart-pytorch-lightning.rst

@@ -1,3 +1,6 @@
+.. _quickstart-pytorch-lightning:
+
+
 Quickstart PyTorch Lightning
 ============================
 

doc/source/quickstart-pytorch.rst

@@ -1,3 +1,6 @@
+.. _quickstart-pytorch:
+
+
 Quickstart PyTorch
 ==================
 

doc/source/quickstart-scikitlearn.rst

@@ -1,3 +1,6 @@
+.. _quickstart-scikitlearn:
+
+
 Quickstart scikit-learn
 =======================
 

doc/source/quickstart-tensorflow.rst

@@ -1,3 +1,6 @@
+.. _quickstart-tensorflow:
+
+
 Quickstart TensorFlow
 =====================
 

doc/source/saving-progress.rst

@@ -1,5 +1,5 @@
-Guide: Saving Progress
-======================
+Saving Progress
+===============
 
 The Flower server does not prescribe a way to persist model updates or evaluation results.
 Flower does not (yet) automatically save model updates on the server-side.

doc/source/ssl-enabled-connections.rst

@@ -1,5 +1,5 @@
-Guide: SSL-enabled Server and Client
-====================================
+SSL-enabled Server and Client
+=============================
 
 This guide describes how to a SSL-enabled secure Flower server can be started and
 how a Flower client can establish a secure connections to it.