Upgrade documentation (1/N)

* Rename docs-requirements.txt to requirements.txt (already under docs folder)
* Update official docs contributing.md
* Point repo CONTRIBUTING.md to docs/contributing.md
* Add OpenFL logo and favicon
* Use new Sphinx Book Theme

Signed-off-by: Shah, Karan <[email protected]>

.readthedocs.yaml

@@ -1,37 +1,23 @@
-# Read the Docs configuration file for Sphinx projects
+# .readthedocs.yml
+# Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-# Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: "ubuntu-22.04"
   tools:
     python: "3.10"
-    # You can also specify other tool versions:
-    # nodejs: "20"
-    # rust: "1.70"
-    # golang: "1.20"
 
-# Build documentation in the "docs/" directory with Sphinx
+# Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
-  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
-  # builder: "dirhtml"
-  # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
+  fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#   - pdf
-#   - epub
+formats:
+  - htmlzip
 
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# Optionally set the version of Python and requirements required to build your docs
 python:
   install:
-    - method: pip
-      path: .
-    - requirements: docs/docs-requirements.txt
+    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -1,79 +1,2 @@
 # Contributing to OpenFL
-
-We welcome contributions from the community. There are several ways to contribute:
-* Improvements in [documentation](https://openfl.readthedocs.io/en/latest/).
-* Contributing to OpenFL's code-base: via bug-fixes or feature additions.
-* Answering questions on our [discussions page](https://github.com/securefederatedai/openfl/discussions).
-* Participating in our [roadmap](https://github.com/securefederatedai/openfl/blob/develop/ROADMAP.md) discussions.
-
-We have a slack [channel](https://join.slack.com/t/openfl/shared_invite/zt-ovzbohvn-T5fApk05~YS_iZhjJ5yaTw) and we host regular [community meetings](https://github.com/securefederatedai/openfl#support).
-
-
-## How to contribute code
-### Step 1. Open an issue
-
-Before you start making any changes, it is always good to open an [issue](https://github.com/securefederatedai/openfl/issues/new/choose) first (assuming one does not already exist), outlining your proposed changes. We can give you feedback, and potentially validate the proposed changes.
-
-For minor changes (akin to a documentation or bug fix), proceed to opening a Pull Request (PR) directly.
-
-### Step 2. Make code changes
-
-To modify code, you need to fork the repository. Set up a development environment as covered in the section "Setup environment" below.
-
-### Step 3. Create a Pull Request (PR)
-
-Once the change is ready, open a PR from your branch in your fork, to the `develop` branch in [securefederatedai/openfl](https://github.com/securefederatedai/openfl). OpenFL follows standard recommendations of PR formatting. Find more details [here](https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/).
-
-### Step 4. Sign your work
-
-Signoff your patch commits using your real name. We discourage anonymous contributions.
-
-    Signed-off-by: Joe Smith <[email protected]>
-
-If you set your `user.name` and `user.email` git configs, you can sign your
-commits using `git commit --signoff`.
-
-Your signature [certifies](http://developercertificate.org/) that you wrote the patch, or, you otherwise have the right to pass it on as an open-source patch.
-
-OpenFL is licensed under the [Apache 2.0 license](https://github.com/securefederatedai/openfl/blob/develop/LICENSE). By contributing to the project, you agree to the license and copyright terms therein and release your contribution under these terms.
-
-### Step 5. Code review and merge
-
-Verify that your contribution passes all tests in our CI/CD pipeline. In case of a failure, like shown below, look into the error messages and try to fix them.
-
-![CI/CD](docs/images/CI_details.png)
-
-Meanwhile, a reviewer will review the pull request and provide comments. Post few iterations of
-reviews and changes (depending on the complexity of the changes), PR will be approved for merge.
-
-## Setup environment
-
-We recommend setting up a local dev environment. Clone your forked repo to your local machine and install the dependencies.
-
-```shell
-git clone https://github.com/YOUR_GITHUB_USERNAME/openfl.git
-cd openfl
-pip install -U pip setuptools wheel
-pip install .
-pip install -r linters-requirements.txt
-```
-
-## Code style
-
-OpenFL uses [ruff](https://github.com/astral-sh/ruff) to lint/format code and [precommit](https://pre-commit.com/) checks.
-
-Run the following command at the **root** directory of the repo to format your code.
-
-```
-sh scripts/format.sh
-```
-You may need to resolve errors that could not be resolved by autoformatting. To only show lint errors, run `sh scripts/lint.sh` at the **root** directory of the repo.
-
-### Docstrings
-Since docstrings cannot be checked or standardized, if you do write/edit any docstring, make sure to check them manually. OpenFL docstrings should follow the conventions below:
-
-A **class** or a **function** docstring may contain:
-* A one-line description of the class/function.
-* Paragraph(s) of detailed information.
-* Optional `Examples` section.
-* `Args` section for arguments under `__init__()`.
+For more information, see [Contributing to OpenFL](https://openfl.readthedocs.io/en/latest/CONTRIBUTING.html).

docs/README.md

@@ -12,7 +12,7 @@ pip install .
 Install requirements for building documentation:
 
 ```sh
-pip install -r docs-requirements.txt
+pip install -r docs/requirements.txt
 ```
 
 

docs/conf.py

@@ -1,8 +1,6 @@
-"""Docs configuration module."""
-
-# Copyright (C) 2020-2023 Intel Corporation
+# Copyright (C) 2020-2024 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
-
+"""Docs configuration module."""
 
 # Configuration file for the Sphinx documentation builder.
 #
@@ -17,6 +15,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import inspect
+import operator
 import sys
 from datetime import datetime
 
@@ -31,17 +31,21 @@
 # import sphinxcontrib.napoleon # NOQA:E800
 
 extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
-    'sphinx_rtd_theme',
-    'sphinx.ext.autosectionlabel',
-    'sphinx-prompt',
+    'sphinx.ext.linkcode',
+    'sphinx.ext.mathjax',
+    'sphinx_remove_toctrees',
     'sphinx_copybutton',
-    'sphinx_substitution_extensions',
-    'sphinx.ext.ifconfig',
+    'sphinx_design',
+    'sphinxext.rediraffe',
     'sphinxcontrib.mermaid',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
-    'recommonmark'
+    'sphinx-prompt',
+    # 'sphinx.ext.ifconfig',
+    # 'sphinx.ext.autosectionlabel',
+    # 'sphinx_substitution_extensions',
+    # 'recommonmark'
 ]
 autodoc_default_options = {
     'imported-members': True,
@@ -51,17 +55,13 @@
 source_suffix = ['.rst', '.md']
 
 # -- Project information -----------------------------------------------------
-
 # This will replace the |variables| within the rST documents automatically
-
-PRODUCT_VERSION = 'Intel'
-
 project = 'OpenFL'
-copyright = f'{datetime.now().year}, Intel'  # NOQA
-author = 'Intel Corporation'
-version = f'{datetime.now().year}.{datetime.now().month}'
-release = version
-master_doc = 'index'
+copyright = f'{datetime.now().year}, The OpenFL Team'
+author = 'The OpenFL Team'
+version = ''
+release = ''
+main_doc = 'index'
 
 # Global variables for rST
 rst_prolog = '''
@@ -126,16 +126,49 @@ def patched_parse(self):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = 'sphinx_rtd_theme'
+html_logo = '_static/openfl_logo.png'
+html_favicon = '_static/favicon.png'
+html_theme = 'sphinx_book_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {
+    'show_toc_level': 2,
+    'repository_url': 'https://github.com/securefederatedai/openfl',
+    'use_repository_button': True,     # add a "link to repository" button
+    'navigation_with_keys': False,
+}
 
 # 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']
-html_style = 'css/Intel_One_Mono_Font_Theme.css'
-autosectionlabel_prefix_document = True
-
-
-def setup(app):
-    app.add_css_file('css/custom.css')
+# html_style = 'css/Intel_One_Mono_Font_Theme.css'
+# Customize code links via sphinx.ext.linkcode
+
+def linkcode_resolve(domain, info):
+  import openfl
+
+  if domain != 'py':
+    return None
+  if not info['module']:
+    return None
+  if not info['fullname']:
+    return None
+  if info['module'].split(".")[0] != 'openfl':
+     return None
+  try:
+    mod = sys.modules.get(info['module'])
+    obj = operator.attrgetter(info['fullname'])(mod)
+    if isinstance(obj, property):
+        obj = obj.fget
+    while hasattr(obj, '__wrapped__'):  # decorated functions
+        obj = obj.__wrapped__
+    filename = inspect.getsourcefile(obj)
+    source, linenum = inspect.getsourcelines(obj)
+  except:
+    return None
+  filename = os.path.relpath(filename, start=os.path.dirname(openfl.__file__))
+  lines = f"#L{linenum}-L{linenum + len(source)}" if linenum else ""
+  return f"https://github.com/securefederatedai/openfl/blob/develop/openfl/{filename}{lines}"

docs/contributing.md

@@ -0,0 +1,79 @@
+# Contributing to OpenFL
+
+We welcome contributions from the community. There are several ways to contribute:
+* Improvements in [documentation](https://openfl.readthedocs.io/en/latest/).
+* Contributing to OpenFL's code-base: via bug-fixes or feature additions.
+* Answering questions on our [discussions page](https://github.com/securefederatedai/openfl/discussions).
+* Participating in our [roadmap](https://github.com/securefederatedai/openfl/blob/develop/ROADMAP.md) discussions.
+
+We have a slack [channel](https://join.slack.com/t/openfl/shared_invite/zt-ovzbohvn-T5fApk05~YS_iZhjJ5yaTw) and we host regular [community meetings](https://github.com/securefederatedai/openfl#support).
+
+
+## How to contribute code
+### Step 1. Open an issue
+
+Before you start making any changes, it is always good to open an [issue](https://github.com/securefederatedai/openfl/issues/new/choose) first (assuming one does not already exist), outlining your proposed changes. We can give you feedback, and potentially validate the proposed changes.
+
+For minor changes (akin to a documentation or bug fix), proceed to opening a Pull Request (PR) directly.
+
+### Step 2. Make code changes
+
+To modify code, you need to fork the repository. Set up a development environment as covered in the section "Setup environment" below.
+
+### Step 3. Create a Pull Request (PR)
+
+Once the change is ready, open a PR from your branch in your fork, to the `develop` branch in [securefederatedai/openfl](https://github.com/securefederatedai/openfl). OpenFL follows standard recommendations of PR formatting. Find more details [here](https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/).
+
+### Step 4. Sign your work
+
+Signoff your patch commits using your real name. We discourage anonymous contributions.
+
+    Signed-off-by: Joe Smith <[email protected]>
+
+If you set your `user.name` and `user.email` git configs, you can sign your
+commits using `git commit --signoff`.
+
+Your signature [certifies](http://developercertificate.org/) that you wrote the patch, or, you otherwise have the right to pass it on as an open-source patch.
+
+OpenFL is licensed under the [Apache 2.0 license](https://github.com/securefederatedai/openfl/blob/develop/LICENSE). By contributing to the project, you agree to the license and copyright terms therein and release your contribution under these terms.
+
+### Step 5. Code review and merge
+
+Verify that your contribution passes all tests in our CI/CD pipeline. In case of a failure, like shown below, look into the error messages and try to fix them.
+
+![CI/CD](docs/images/CI_details.png)
+
+Meanwhile, a reviewer will review the pull request and provide comments. Post few iterations of
+reviews and changes (depending on the complexity of the changes), PR will be approved for merge.
+
+## Setup environment
+
+We recommend setting up a local dev environment. Clone your forked repo to your local machine and install the dependencies.
+
+```shell
+git clone https://github.com/YOUR_GITHUB_USERNAME/openfl.git
+cd openfl
+pip install -U pip setuptools wheel
+pip install .
+pip install -r linters-requirements.txt
+```
+
+## Code style
+
+OpenFL uses [ruff](https://github.com/astral-sh/ruff) to lint/format code and [precommit](https://pre-commit.com/) checks.
+
+Run the following command at the **root** directory of the repo to format your code.
+
+```
+sh scripts/format.sh
+```
+You may need to resolve errors that could not be resolved by autoformatting. To only show lint errors, run `sh scripts/lint.sh` at the **root** directory of the repo.
+
+### Docstrings
+Since docstrings cannot be verified programmatically, if you do write/edit a docstring, make sure to check them manually. OpenFL docstrings should follow the conventions below:
+
+A **class** or a **function** docstring may contain:
+* A one-line description of the class/function.
+* Paragraph(s) of detailed information.
+* Usage examples wherever applicable.
+* Detailed description of function arguments, return types and possible exceptions raised.