Substra documentation

Substra is an open source federated learning (FL) software. This specific repository is the documentation of Substra.

This documentation is hosted on Read The Docs and can be found here.

Support

If you need support, please either raise an issue on Github or ask on Slack.

Setup

Contributing

If you would like to contribute to this documentation please clone it locally and make a new branch with the suggested changes.

You should use python 3.10.

To deploy the documentation locally you need to install all the necessary requirements which you can find in the 'requirements.txt' file of the root of this repository. You can use pip in your terminal to install it: pip install -r requirements.txt.

You also need to manually install pandoc.

Install substra, substratools and substrafl in editable mode

⚠️ if you have these repositories installed in non-editable mode, it will not work.

Install the repositories in editable mode:

git clone git@github.com:Substra/substra.git
cd substra && pip install -e . && cd ..

git clone git@github.com:Substra/substra-tools.git
cd substra-tools && pip install -e . && cd ..

git clone git@github.com:Substra/substrafl.git
cd substrafl && pip install -e '.[dev]' && cd ..

Build the documentation locally

Next, to build the documentation move to the docs directory: cd docs

And then: make clean html

The first time you run it or if you updated the examples library it may take a little longer to build the whole documentation.

To see the doc on your browser : make livehtml And then go to http://127.0.0.1:8000

Once you are happy with your changes push your branch and make a pull request.

Thank you for helping us improving!

Add a new example

• Put the example folder in substra-documentation/examples if it is a Substra example, substra-documentation/substrafl_examples if it is a Substrafl example.

• create a README.rst file at the root of the example

• The main file that is executed must match the regex run_*.py, e.g. run_titanic.py (source)

• It must also be structured as described in the Sphinx gallery documentation. In particular, the folder containing the run_*.py example file must contain a README.rst file.

• Add the assets:

  • use the zip_dir function in the conf.py file to zip the assets

  • add the link to download the assets to the example's docstring:

    .. only:: builder_html or readthedocs
    
        :download:`assets required to run this example <../../ASSET_NAME.zip>`

• thumbnail: add the path to the image in a comment in a cell of the example

  # sphinx_gallery_thumbnail_path = 'auto_examples/EXAMPLE_FOLDER_NAME/images/thumb/sphx_glr_plot_thumb.jpg'

Releases

The documentation is released for each Substra release. When a semver tag is pushed or a release is created, the doc is builded and published to ReadTheDocs by the CI. Then ReadTheDocs automatically activates this version and set it as default (takes a few minutes). You can follow the build on the CI here and on ReadTheDocs if you have access to the project.

How to generate the changelog

The changelog is managed with towncrier. To add a new entry in the changelog, add a file in the changes folder. The file name should have the following structure: <unique_id>.<change_type>. The unique_id is a unique identifier, we currently use the PR number. The change_type can be of the following types: added, changed, removed, fixed.

To generate the changelog (for example during a release), use the following command (you must have the dev dependencies installed):

towncrier build --version=<x.y.z>

You can use the --draft option to see what would be generated without actually writing to the changelog (and without removing the fragments).