From 06b9da61f6821a97e0462353e267cc15295a30f8 Mon Sep 17 00:00:00 2001 From: Fabien GELUS <45175277+Fabien-GELUS@users.noreply.github.com> Date: Fri, 7 Jan 2022 18:10:22 +0100 Subject: [PATCH] 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 --- .../{publish.yml => publish_latest.yml} | 4 -- .github/workflows/publish_stable.yml | 62 +++++++++++++++++++ CHANGELOG.md | 1 + README.md | 15 +++-- docs/source/conf.py | 17 ++++- docs/source/documentation/api_reference.rst | 2 + examples/README.rst | 2 + 7 files changed, 92 insertions(+), 11 deletions(-) rename .github/workflows/{publish.yml => publish_latest.yml} (94%) create mode 100644 .github/workflows/publish_stable.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish_latest.yml similarity index 94% rename from .github/workflows/publish.yml rename to .github/workflows/publish_latest.yml index 1cd7b770..14f7d88e 100644 --- a/.github/workflows/publish.yml +++ b/.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: diff --git a/.github/workflows/publish_stable.yml b/.github/workflows/publish_stable.yml new file mode 100644 index 00000000..49ec649e --- /dev/null +++ b/.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 }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 969ddb56..0cfbe28d 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index e040be03..a694954f 100644 --- a/README.md +++ b/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). diff --git a/docs/source/conf.py b/docs/source/conf.py index dbecfe6c..801896c4 100644 --- a/docs/source/conf.py +++ b/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", diff --git a/docs/source/documentation/api_reference.rst b/docs/source/documentation/api_reference.rst index 2fd0b352..7616bf16 100644 --- a/docs/source/documentation/api_reference.rst +++ b/docs/source/documentation/api_reference.rst @@ -1,6 +1,8 @@ API reference ============= +`substra` version: |substra_version| + CLI Reference ------------- .. toctree:: diff --git a/examples/README.rst b/examples/README.rst index f34100cc..8fbd9c0a 100644 --- a/examples/README.rst +++ b/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