diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6ad203d6291..3daed68191a 100644 --- a/.readthedocs.yaml +++ b/.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 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 254b64a38fd..8fdf17377f2 100644 --- a/CONTRIBUTING.md +++ b/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 - -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). \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index fbab187dc19..82b44ca14c5 100644 --- a/docs/README.md +++ b/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 ``` diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png new file mode 100644 index 00000000000..77d8bf48027 Binary files /dev/null and b/docs/_static/favicon.png differ diff --git a/docs/_static/openfl_logo.png b/docs/_static/openfl_logo.png new file mode 100644 index 00000000000..3158a5b5cf8 Binary files /dev/null and b/docs/_static/openfl_logo.png differ diff --git a/docs/conf.py b/docs/conf.py index bc5857847e5..edd76266ec0 100644 --- a/docs/conf.py +++ b/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}" \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000000..220a9693490 --- /dev/null +++ b/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 + +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. \ No newline at end of file diff --git a/docs/contributing_guidelines/contributing.md b/docs/contributing_guidelines/contributing.md deleted file mode 100644 index 2f6ec5e9541..00000000000 --- a/docs/contributing_guidelines/contributing.md +++ /dev/null @@ -1,102 +0,0 @@ -Contributing to OpenFL -===================================================================== - -We welcome contributions from the community. We believe that anyone can bring something valuable to OpenFL and help us to improve the project. This document explains how to contribute to OpenFL. - -We accept various contributions from documentation improvement and bug fixing to major features proposals and [roadmap](https://github.com/intel/openfl/blob/develop/ROADMAP.md) suggestions. - -Documentation improvement: review our [documentation](https://openfl.readthedocs.io/en/latest) and let us know if something is not clear or not relevant. -Propose your own formulations or even write new section explaining something that you know how works, but do not see in the documentation. -Propose it through GitHub [issues](https://github.com/intel/openfl/issues/new/choose) or [Discussions](https://github.com/intel/openfl/discussions). - -To propose bugs, new features, or other code improvements: - -1. Check open and closed [issues](https://github.com/intel/openfl/issues) and make sure there is no similar proposal. -2. Open a [new issue](https://github.com/intel/openfl/issues/new/choose), select a relevant category (Bug report / Feature request / Report a security vulnerability) and describe your idea using the template. -3. If you want to fix a bug or create this feature by yourself, prepare a contribution. - - Format your code following the [flake8 style](https://flake8.pycqa.org/en/latest/). - - Make sure that your code is original and corresponds to [OpenFL license](#license). - - Sing your work - [see below](#sign-your-work). - - Create a [pull request](#formatting-of-pull-requests) and wait for feedback. - - Verify that all tests in our [CI/CD pipeline](#Continuous-Integration-and-Continuous-Development) passed. -4. Hurrah! You are a new contributor to OpenFL! You will see your name in released notes of the subsequent releases!😊 - -Join our [Slack](https://join.slack.com/t/openfl/shared_invite/zt-ovzbohvn-T5fApk05~YS_iZhjJ5yaTw) and [Community meetings](https://github.com/intel/openfl#support) and participate in the discussions. - -Are you an expert in Federated Learning and want to contribute to our roadmap? You can nominate yourself as a member of our Technical Steering Committee and be part of the OpenFL decision making group. Please reach us through our [Slack](https://join.slack.com/t/openfl/shared_invite/zt-ovzbohvn-T5fApk05~YS_iZhjJ5yaTw). - -### Code format and style - -We use [flake8](https://flake8.pycqa.org/en/latest/) for PEP8 style guide enforcement. This is run as a part of our CI/CD pipeline and it’s required prior a merge. - -### Formatting of Pull Requests - -OpenFL follows standard recommendations of PR formatting. Please find more details [here](https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/). - -### Continuous Integration and Continuous Development - -OpenFL uses GitHub actions to perform all functional and unit tests. Before your contribution can be merged make sure that all your tests are passing. -For more information of what fails you can click on the “details” link near the pipeline that failed. - -![CI/CD](../images/CI_details.png) - -### Writing the tests - -The OpenFL team recommend including tests for all new features contributions. Test can be found in the “Tests” directory. -The [Tests/OpenFL folder](https://github.com/intel/openfl/tree/develop/tests/openfl) contains unit tests and the [Tests/GitHub folder](https://github.com/intel/openfl/tree/develop/tests/github) contains end-to-end and functional tests. - -### License - -OpenFL is licensed under the terms in [Apache 2.0 license](https://github.com/intel/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. - -### Sign your work - -Please use the sign-off line at the end of the patch. Your signature certifies that you wrote the patch or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify -the below (from [developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -Then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -Use your real name (sorry, no pseudonyms or anonymous contributions.) - -If you set your `user.name` and `user.email` git configs, you can sign your -commit automatically with `git commit -s`. diff --git a/docs/docs-requirements.txt b/docs/requirements.txt similarity index 74% rename from docs/docs-requirements.txt rename to docs/requirements.txt index f5e5832d9d7..0560ac036d7 100644 --- a/docs/docs-requirements.txt +++ b/docs/requirements.txt @@ -5,6 +5,9 @@ recommonmark sphinx>=3.0.4 # not directly required, pinned by Snyk to avoid a vulnerability sphinx-copybutton sphinx-prompt -sphinx-rtd-theme -sphinx_substitution_extensions +sphinx-book-theme +sphinx_substitution_extensions sphinxcontrib-mermaid +sphinx-remove-toctrees +sphinx-design +sphinxext-rediraffe \ No newline at end of file