Building from source

First, clone the FedJAX source code:

git clone
cd fedjax

Then install the fedjax Python package:

pip install -e .

To upgrade to the latest version from GitHub, inside of the repository root, just run

git pull

You shouldn’t have to reinstall fedjax because pip install -e sets up symbolic links from site-packages into the repository.

Running the tests

We created a simple script for running tests. See its comments for examples. Before creating a pull request, we recommend running all the FedJAX tests (i.e. running with no arguments) to verify the correctness of a change.

Updating the docs

Install the requirements

pip install -r docs/requirements.txt

Then run

sphinx-autobuild -b html --watch . --open-browser docs docs/_build/html

sphinx-autobuild will watch for file changes and auto build the HTML for you, so all you’ll have to do is refresh the page. If you don’t want to use the auto builder, you can just use:

sphinx-build -b html docs docs/_build/html

and then navigate to docs/_build/html/index.html in your browser.

How to write code documentation

Our documentation it is written in ReStructuredText for Sphinx. This is a meta-language that is compiled into online documentation. For more details see Sphinx’s documentation.

We also rely heavily on sphinx.ext.autodoc to convert docstrings in source to rst for Sphinx, so it would be best to be familiar with its directives.

As a result, our docstrings adhere to a specific syntax that has to be kept in mind. Below we provide some guidelines.

How to use “code font”

When writing code font in a docstring, please use double backticks.

# This returns a ``str`` object.

How to write math

We’re using sphinx.ext.mathjax. Then we use the math directive and role to either inline or block notation.

# Blocked notation
# .. math::
#		x + y

# Inline notation :math:`x + y`


Take a look at docs/fedjax.metrics.rst to get a good idea of what to do.

Update notebooks

It is easiest to edit the notebooks in Jupyter or in Colab. To edit notebooks in the Colab interface, open and Upload ipynb from your local repo. Update it as needed, Run all cells then Download ipynb to your local repo. You may want to test that it executes properly, using sphinx-build as explained above. We recommend making changes this way to avoid introducing format errors into the .ipynb files.

In the future, we may build and re-execute the notebooks as part of the Read the docs build. However, for now, we exclude all notebooks from the build due to long durations (downloading dataset files, expensive model training, etc.). See exclude_patterns in