Create inital documentation (adap#55)

dev/venv-create.sh

@@ -3,3 +3,4 @@ set -e
 cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"/../
 
 pyenv virtualenv 3.7.6 flower-3.7.6
+echo flower-3.7.6 > .python-version

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

doc/source/conf.py

@@ -0,0 +1,54 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Flower"
+copyright = "2020, Adap GmbH"
+author = "The Flower Authors"
+
+# The full version, including alpha/beta/rc tags
+release = "0.0.1"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

doc/source/examples.rst

@@ -0,0 +1,65 @@
+Usage 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
+pipelines, usually leveraging popular machine learning frameworks such as
+`PyTorch <https://pytorch.org/>`_ or
+`TensorFlow <https://www.tensorflow.org/>`_.
+
+
+Extra Dependencies
+------------------
+
+The core Flower framework tries to keep a minimal set of dependencies. Because
+the examples demonstrate Flower in the context of differnt machine learning
+frameworks, one needs to install those additional dependencies before running
+an example::
+
+  $ pip install git+https://github.com/adap/flower.git#egg=flower[examples-tensorflow]
+
+The previous command installs the extra :code:`examples-tensorflow`. Please
+consult :code:`pyproject.toml` for a full list of possible extras (section
+:code:`[tool.poetry.extras]`).
+
+
+PyTorch Examples
+----------------
+
+PyTorch examples will follow shortly. Stay tuned!
+
+
+TensorFlow Examples
+-------------------
+
+Our TensorFlow examples are based on TensorFlow 2.0 or newer. So far, we
+provide the following examples.
+
+MNIST Image Classification
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`MNIST <http://yann.lecun.com/exdb/mnist/>`_ is often used as the "Hello,
+world!" of machine learning. We follow this tradition and provide an example
+which samples random local datasets from MNIST and trains a simple image
+classification model over those partitions.
+
+First, start a Flower server:
+
+  $ python -m flower_examples.tf_mnist_grpc_server
+
+For each Flower client that should participate in the trainig, open a new
+terminal window and type:
+
+  $ python -m flower_examples.tf_mnist_grpc_client
+
+For more details, see :code:`src/flower_examples/tf_mnist_grpc_server.py` and
+:code:`src/flower_examples/tf_mnist_grpc_client.py`. 
+
+MNIST Image Classification (single-machine)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is also a single-machine version of the previous MNIST image
+classification example. It executes both client and server in a single process,
+which might be handy for some types of experimentation. To run it, type::
+
+  $ python src/flower_examples/mnist.py

doc/source/getting-started-for-contributors.rst

@@ -0,0 +1,97 @@
+Getting Started (for Contributors)
+==================================
+
+Prerequisites
+-------------
+
+- `Python 3.7 <https://docs.python.org/3.7/>`_ or above
+- `Poetry 1.0 <https://python-poetry.org/>`_ or above
+- (Optional) `pyenv <https://github.com/pyenv/pyenv>`_
+- (Optional) `pyenv-virtualenv <https://github.com/pyenv/pyenv-virtualenv>`_
+
+Flower uses :code:`pyproject.toml` to manage dependencies and configure
+development tools (the ones which support it). Poetry is a build tool which
+supports `PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_.
+
+
+Developer Machine Setup
+-----------------------
+
+First, clone the `Flower repository <https://github.com/adap/flower>`_ from
+GitHub::
+
+  $ git clone [email protected]:adap/flower.git
+  $ cd flower
+
+Second, create a virtual environment (and activate it). If you chose to use
+:code:`pyenv` (with the :code:`pyenv-virtualenv` plugin), you can use the
+following convenience script::
+
+  $ ./dev/venv-create.sh
+
+Third, install the Flower package in development mode (think
+:code:`pip install -e`) along with all necessary dependencies::
+
+  (flower-3.7.6) $ ./dev/bootstrap.sh
+
+
+Convenience Scripts
+-------------------
+
+The Flower repository contains a number of convenience scripts to make
+recurring development tasks easier and less error-prone. See the :code:`/dev`
+subdirectory for a full list. The following scripts are amonst the most
+important ones:
+
+Create/Delete Virtual Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+  $ ./dev/venv-create.sh
+  $ ./dev/venv-delete.sh
+
+Compile ProtoBuf Definitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+  $ python -m flower_tools.protoc
+
+Auto-Format Code
+~~~~~~~~~~~~~~~~
+
+::
+
+  $ ./dev/format.sh
+
+Run Linters and Tests
+~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+  $ ./dev/test.sh
+
+
+Build Release
+-------------
+
+Flower uses Poetry to build releases. The necessary command is wrapped in a
+simple script::
+
+  $ ./dev/build.sh
+
+The resulting :code:`.whl` and :code:`.tar.gz` releases will be stored in the
+:code:`/dist` subdirectory.
+
+
+Build Documentation
+-------------------
+
+Flower's documentation uses `Sphinx <https://www.sphinx-doc.org/>`_. There's no
+convenience script to re-build the documentation yet, but it's pretty easy::
+
+  $ cd doc
+  $ make html
+
+This will generate HTML documentation in ``doc/build/html``.

doc/source/good-first-contributions.rst

@@ -0,0 +1,34 @@
+Good First Contributions
+========================
+
+We welcome contributions to Flower! However, it is not always easy to know
+where to start. We therefore put together a few recommendations on where to
+start to increase your chances of getting your PR accepted into the Flower
+codebase.
+
+
+Where to Start
+--------------
+
+Until the Flower core library matures it will be easier to get PR's accepted if
+they only touch non-core areas of the codebase. Good candidates to get started
+are:
+
+- Documentation: What's missing? What could be expressed more clearly? 
+- Examples: See below.
+
+
+Request for Examples
+--------------------
+
+We wish we had more time to write usage examples because we believe they help
+users to get started with building what they want to build. Here are a few
+ideas where we'd be happy to accept a PR:
+
+- First scikit-learn example (MNIST)
+- First MXNet 1.6 example (MNIST)
+- CIFAR-10/100 (PyTorch/TensorFlow)
+- ImageNet (PyTorch/TensorFlow)
+- LSTM (PyTorch/TensorFlow)
+- Transformer (PyTorch/TensorFlow)
+- BERT (PyTorch/TensorFlow)

doc/source/index.rst

@@ -0,0 +1,48 @@
+Welcome to Flower's documentation!
+==================================
+
+Flower is a friendly federated learning research framework. The design of
+Flower is based on a few guiding principles which aim to make it
+*customizable*, *extendable*, *framework-agnostic*, and hopefully also
+*understandable*.
+
+
+User Guide
+----------
+
+The user guide is targeted at 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.
+
+.. warning:: Flower's user-facing API is still in development and not
+   considered stable. We welcome curious users to give it a try and share their
+   experience with us.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide Contents:
+
+   installation
+   examples
+
+
+Contributor Guide
+-----------------
+
+The Flower authors welcome external contributions. The following guides are
+intended to help along the way.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contributor Guide Contents:
+
+   getting-started-for-contributors
+   good-first-contributions
+
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/installation.rst

@@ -0,0 +1,27 @@
+Installing Flower
+=================
+
+
+Python Version
+--------------
+
+Flower requires `Python 3.7 <https://docs.python.org/3.7/>`_ or above.
+
+
+Install from GitHub
+-------------------
+
+Python packages can be installed from git repositories. Use the following
+command to install the latest version of Flower directly from GitHub::
+
+  $ pip install git+https://github.com/adap/flower.git
+
+One can also install a specific commit::
+
+  $ pip install git+https://github.com/adap/flower.git@147541d3d4c0ddb4f215fef57f8adf57f8c126b1
+
+
+A Note on PyPI
+-----------------
+
+For now, there are no `PyPI <https://pypi.org/>`_ releases. Official PyPI releases will follow once the API matures.