feat: Substra versioning (#18)

* install latest release of substra when publish new release

* show substra version in epilog for each page

* automate doc version, put substra version with doc version

* update contrib

* changelog

* add substra version

* manual substra version

* fix workflow

* Explain release

* comments

.github/workflows/publish.yml → .github/workflows/publish_latest.yml

@@ -1,14 +1,10 @@
 name: Sphinx Build and RTD publish
 
 on:
-  release:
-    types: [published]
   push:
     branches:
       - main
     # Pattern matched against refs/tags
-    tags:
-      - '*'           # Push events to every tag not containing /
 
 jobs:
   build:

.github/workflows/publish_stable.yml

@@ -0,0 +1,62 @@
+name: Sphinx Build and RTD publish for releases = stable versions
+
+env:
+  SUBSTRA_VERSION: 0.14.0  # RELEASE: put the substra version associated with the connect release here
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - '*'           # Push events to every tag not containing /
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+
+      - name: Clone substra
+        uses: actions/checkout@v2
+        with:
+          repository: owkin/substra
+          token: ${{ secrets.ACCESS_TOKEN }}
+          path: substra
+          ref: ${{ env.SUBSTRA_VERSION }}
+
+      - name: Install substra
+        run: pip install -e substra
+
+      - name: Copy substra api doc in the doc
+        run: cp -r substra/references docs/source/documentation/references
+
+      - name: Install requirements
+        run: pip install -r requirements.txt
+
+      - name: Sphinx make
+        working-directory: ./docs
+        run: make clean && make html
+
+      # exchange the absolute path given by sphinx-gallery with relative path
+      - name: replace absolute paths
+        run: sed -i "s+//home/runner/work/connect-documentation/connect-documentation/docs/source/auto_examples/++g;" docs/source/auto_examples/index.rst
+
+      - uses: actions/upload-artifact@v2
+        with:
+          name: build-for-${{ github.sha }}
+          path: docs/source/
+
+      - name: Trigger RTDs build
+        # TODO: for now using personal repo because of changes which needed to be applied
+        # to the action so it works on private repos. Once the original one is published it should be updated to:
+        # dfm/rtds-action  -> commit of interest 66a4e12
+        uses: maikia/rtds-action@v1
+        with:
+          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
+          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
+          commit_ref: ${{ github.ref }}

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- feat: Substra versioning (#18)
 - doc:  include Substra API Reference (#17)
 ## [0.1.1] - 2021-12-07
 ### Added

README.md

@@ -30,8 +30,8 @@ Thank you for helping us improving!
     # See the tags
     git tag
     # Add a new tag
-    git tag -a X.X.X-your-branch
-    git push origin X.X.X-your-branch
+    git tag -a dev-your-branch
+    git push origin dev-your-branch
 ```
 
 Check the publish action is running: https://github.com/owkin/connect-documentation/actions
@@ -40,7 +40,14 @@ Activate your version on RTD (need admin rights): https://readthedocs.com/projec
 
 Follow the build here : https://readthedocs.com/projects/owkin-connect-documentation/builds/
 
-See the doc on https://owkin-connect-documentation.readthedocs-hosted.com/en/X.X.X-your-branch
+See the doc on https://owkin-connect-documentation.readthedocs-hosted.com/en/dev-your-branch
 
 If everything is OK, you can delete your version on RTD (wipe button): https://readthedocs.com/projects/owkin-connect-documentation/versions/
-and delete your tag : `git push --delete origin X.X.X-your-branch`
+and delete your tag : `git push --delete origin dev-your-branch`
+
+## Releases
+
+The doc is released for each Connect release. The release guide is in the [tech-team repo](https://github.com/owkin/tech-team/blob/main/releasing_guide.md#release-connect-and-connect-documentation).
+
+When a semver tag is pushed or a release is created, the doc is builded and published to RTD by the [CI](https://github.com/owkin/connect-documentation/.github/workflows/publish_stable.yml).
+Then RTD [automatically](https://readthedocs.com/dashboard/owkin-connect-documentation/rules/regex/411/) activate this version and set it as default (takes a few minutes).

docs/source/conf.py

@@ -90,14 +90,21 @@ def reformat_md_section_links(file_path: Path):
 # TODO: change those sections names in substra ? Or ignore warnings just for those files
 suppress_warnings = ['autosectionlabel.*']
 
+
 # -- Project information -----------------------------------------------------
 
+
+
 project = u"Connect"
 copyright = u"2020, OWKIN"
 author = u"Owkin"
+
+# parse the current doc version to display it in the menu
+_doc_version = re.sub('^v', '', os.popen('git describe --tags').read().strip())
 # The full version, including alpha/beta/rc tags
-version = '0.1.1'  # TODO: include _get_version() when ready
-release = version
+version = _doc_version
+release = _doc_version
+
 # if sphinx is building on rtd it will use example gallery generated by CI
 # it cannot generate its own gallery as it cannot run docker
 on_rtd = os.environ.get('READTHEDOCS') == 'True'
@@ -178,6 +185,11 @@ def reformat_md_section_links(file_path: Path):
 # Generate the plot for the gallery
 # plot_gallery = True
 
+
+rst_epilog = f"""
+.. |substra_version| replace:: {substra.__version__}
+"""
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -208,7 +220,6 @@ def reformat_md_section_links(file_path: Path):
     "display_github": False,
 }
 
-
 if not on_rtd:
     sphinx_gallery_conf = {
         "doc_module": "substra",

docs/source/documentation/api_reference.rst

@@ -1,6 +1,8 @@
 API reference
 =============
 
+`substra` version: |substra_version|
+
 CLI Reference
 -------------
 .. toctree::

examples/README.rst

@@ -1,4 +1,6 @@
 Examples to get started
 =======================
 
+`substra` version: |substra_version|
+
 If you are a beginner feel free to follow one of the examples below