adap · tanertopal · Aug 19, 2022 · Aug 19, 2022 · Aug 19, 2022 · Aug 19, 2022
@@ -1,31 +1,35 @@
 <!--
-Thanks for contributing a pull request! Please ensure you have taken a look at
+Thank you for opening a pull request! Please ensure you have taken a look at
 the contribution guidelines: https://github.com/adap/flower/blob/main/CONTRIBUTING.md
 
+Does the documentation need to be updated?
+See: https://flower.dev/docs/writing-documentation.html
+
 Does the changelog need to be updated?
 See: https://github.com/adap/flower/blob/main/doc/source/changelog.rst
 -->
 
 #### Reference Issues/PRs
 
 <!--
-Example: Fixes #1234. See also #3456.
 Please use keywords (e.g., Fixes) to create a link to the issues or pull requests
 you resolved.
+
+Example: Fixes #123. See also #456 and #789.
 -->
 
 #### What does this implement/fix? Explain your changes.
 
 <!--
 Explain why this PR is needed and what kind of changes have you done.
-Example: the variable `rnd` could be interpreted as an abbreviation of *random*, to improve clarity it was renamed to `server_round`. 
+
+Example: The variable `rnd` could be interpreted as an abbreviation of *random*, to improve clarity it was renamed to `server_round`.
 -->
 
 #### Any other comments?
 
-
 <!--
-Please be aware that it may take some time until we can check this PR. 
+Please be aware that it may take some time until the maintainers can review the PR.
 If you have an urgent request or question please use the Flower Slack channel.
 The Slack channel is really active and contributors respond pretty fast. 
 

@@ -51,6 +51,7 @@ Flower's design goals was to make this simple. Read on to learn more.
    changelog
    faq
 
+
 Flower Baselines
 ----------------
 
@@ -87,6 +88,7 @@ intended to help along the way.
    getting-started-for-contributors
    good-first-contributions
    contributor-setup
+   writing-documentation
    architecture
    secagg
    release-process

@@ -4,6 +4,7 @@ Secure Aggregation Protocols
 Include SecAgg, SecAgg+, and LightSecAgg protocol. The LightSecAgg protocol has not been implemented yet, so its diagram and abstraction may not be accurate in practice.
 The SecAgg protocol can be considered as a special case of the SecAgg+ protocol.
 
+
 The :code:`SecAgg+` abstraction
 -------------------------------
 
@@ -62,8 +63,6 @@ In this implementation, each client will be assigned with a unique index (int) f
         ) -> UnmaskVectorsResultsAndFailures:
             """Unmask and compute the aggregated model. UnmaskVectorRes contains shares of keys needed to generate masks."""
 
-
-
 The Flower server will execute and process received results in the following order:
 
 .. mermaid::
@@ -156,6 +155,7 @@ The Flower server will execute and process received results in the following ord
       deactivate P
       end
 
+
 The :code:`LightSecAgg` abstraction
 -----------------------------------
 
@@ -196,7 +196,6 @@ In this implementation, each client will be assigned with a unique index (int) f
         ) -> AskAggregatedEncodedMasksResultsAndFailures:
             """Ask aggregated encoded masks"""
 
-
 The Flower server will execute and process received results in the following order:
 
 .. mermaid::
@@ -268,6 +267,7 @@ The Flower server will execute and process received results in the following ord
       deactivate P
       end
 
+
 Types
 -----
 
@@ -428,4 +428,3 @@ Types
         @dataclass
         class AskAggregatedEncodedMasksRes:
             aggregated_encoded_mask: Parameters
-
@@ -11,6 +11,7 @@ The code example comes with a README.md file which will explain how to start it.
 already SSL-enabled, it might be less descriptive on how. Stick to this guide for a deeper
 introduction to the topic.
 
+
 Certificates
 ------------
 
@@ -35,6 +36,7 @@ sources regarding the issue of correctly generating certificates for production
 In case you are a researcher you might be just fine using the self-signed certificates generated using
 the scripts which are part of this guide.
 
+
 Server
 ------
 
@@ -58,6 +60,7 @@ We are now going to show how to write a sever which uses the previously generate
 
 When providing certificates, the server expects a tuple of three certificates. :code:`Path` can be used to easily read the contents of those files into byte strings, which is the data type :code:`start_server` expects.
 
+
 Client
 ------
 
@@ -81,16 +84,18 @@ We are now going to show how to write a client which uses the previously generat
 When setting :code:`root_certificates`, the client expects the PEM-encoded root certificates as a byte string.
 We are again using :code:`Path` to simplify reading those as byte strings.
 
+
 Conclusion
 ----------
 
 You should now have learned how to generate self-signed certificates using the given script, start a
 SSL-enabled server, and have a client establish a secure connection to it.
 
+
 Additional Resources
 --------------------
 
 These additional sources might be relevant if you would like to dive deeper into the topic of certificates:
 
-* `Let's Encrypt <https://letsencrypt.org/docs/>_`
+* `Let's Encrypt <https://letsencrypt.org/docs/>`_
 * `certbot <https://certbot.eff.org/>`_
@@ -9,6 +9,7 @@ There are three ways to customize the way Flower orchestrates the learning proce
 * Customize an existing strategy with callback functions
 * Implement a novel strategy
 
+
 Use an existing strategy
 ------------------------
 
@@ -81,6 +82,7 @@ Configuring server-side evaluation
 
 Server-side evaluation can be enabled by passing an evaluation function to :code:`evaluate_fn`.
 
+
 Implement a novel strategy
 --------------------------
 

@@ -3,6 +3,7 @@ Upgrade to Flower 1.0
 
 Flower 1.0 is here. Along with new features, Flower 1.0 provides a stable foundation for future growth. Compared to Flower 0.19 (and other 0.x series releases), there are a few breaking changes that make it necessary to change the code of existing 0.x-series projects.
 
+
 Install update
 --------------
 
@@ -18,6 +19,7 @@ Here's how to update an existing installation to Flower 1.0 using either pip or
   - ``flwr = "^1.0.0"`` (when using ``start_server`` and ``start_client``)
   - ``flwr = { version = "^1.0.0", extras = ["simulation"] }`` (when using ``start_simulation``)
 
+
 Required changes
 ----------------
 
@@ -82,6 +84,7 @@ Along with the necessary changes above, there are a number of potential improvem
 - Remove "placeholder" methods from subclasses of ``Client`` or ``NumPyClient``. If you, for example, use server-side evaluation, then empy placeholder implementations of ``evaluate`` are no longer necessary.
 - Configure the round timeout via ``start_simulation``: ``start_simulation(..., config=flwr.server.ServerConfig(num_rounds=3, round_timeout=600.0), ...)``
 
+
 Further help
 ------------
 

@@ -1,6 +1,7 @@
 Using Baselines
 ===============
 
+
 Structure
 ---------
 
@@ -24,6 +25,7 @@ Go to the baseline that you want to execute. The directories and files are struc
 
 The experiment area contains a :code:`README.md` covering the corresponding paper, its abstract, and goal as well as a detailed description of how to run the baseline. Please use the :code:`README.md` to see how to execute each individual baseline.
 
+
 Available Baselines
 -------------------
 

@@ -0,0 +1,26 @@
+Writing documentation
+=====================
+
+
+Project layout
+--------------
+
+The Flower documentation lives in the ``doc`` directory. The Sphinx-based documentation system supports both reStructuredText (``.rst`` files) and Markdown (``.md`` files).
+
+
+Edit an existing page
+---------------------
+
+1. Edit an existing ``.rst`` (or ``.md``) file under ``doc/source/``
+2. Compile the docs: ``cd doc``, then ``poetry run make html``
+3. Open ``doc/build/html/index.html`` in the browser to check the result
+
+
+Create a new page
+-----------------
+
+1. Add new ``.rst`` file under ``doc/source/``
+2. Add content to the new ``.rst`` file
+3. Link to the new rst from ``index.rst``
+4. Compile the docs: ``cd doc``, then ``poetry run make html``
+5. Open ``doc/build/html/index.html`` in the browser to check the result