Merge pull request atomvm#828 from UncleGrumpy/publish_docs

Publish documentation for tag releases

.github/workflows/build-docs.yaml

@@ -0,0 +1,97 @@
+#
+#  Copyright 2023 Winford (Uncle Grumpy) <winford@object.stream>
+#
+#  SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+#
+# This is a workflow for atomvm/AtomVM to Publish API documentation and other content from the `doc` directory to
+# atomvm.net hosted on GitHub Pages
+
+name: Build Docs
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push request and tag events on master branch
+  pull_request:
+    branches:
+      - 'master'
+  push:
+    tags:
+      - '*'
+    branches:
+      - '!master'
+    paths:
+      - '.github/workflows/**'
+      - 'CMakeLists.txt'
+      - 'doc/**'
+      - 'libs/**'
+      - 'src/libAtomVM/**'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }}
+  cancel-in-progress: true
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+
+      - name: Install Deps
+        run: |
+          sudo apt update -y
+          DEBIAN_FRONTEND=noninteractive sudo apt install -y git cmake doxygen graphviz python3-pip python3-virtualenv python3-setuptools python3-stemmer wget
+
+      - uses: actions/cache@v3
+        id: sphinx-cache
+        with:
+          path: /home/runner/python-env/sphinx
+          key: ${{ runner.os }}-sphinx-install
+
+      - name: Install Sphinx
+        if: steps.cache.outputs.sphinx-cache-hit != 'true'
+        run: |
+          python3 -m venv /home/runner/python-env/sphinx
+          . /home/runner/python-env/sphinx/bin/activate
+          python3 -m pip install sphinx
+          python3 -m pip install myst-parser
+          python3 -m pip install sphinx-rtd-theme
+          python3 -m pip install rinohtype
+          python3 -m pip install pillow
+          python3 -m pip install gitpython
+          python3 -m pip install breathe
+          python3 -m pip install pygments
+
+      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: "25"
+          elixir-version: "1.15"
+
+      - name: Install rebar3
+        working-directory: /tmp
+        run: |
+          wget https://s3.amazonaws.com/rebar3/rebar3 && chmod +x rebar3
+          ./rebar3 local install
+          echo "/home/runner/.cache/rebar3/bin" >> ${GITHUB_PATH}
+
+      - uses: actions/checkout@v3
+        with:
+          repository: ${{ vars.GITHUB_REPOSITORY }}
+          fetch-depth: 0
+
+      - name: Build Site
+        shell: bash
+        run: |
+          . /home/runner/python-env/sphinx/bin/activate
+          mkdir build
+          cd build
+          cmake ..
+          cd doc
+          make GitHub_CI_Publish_Docs

.github/workflows/publish-docs.yaml

@@ -10,8 +10,12 @@ name: Publish Docs
 
 # Controls when the workflow will run
 on:
-  # Triggers the workflow on push request events for all branches
+  # Triggers the workflow on push request and tag events on master branch
   push:
+    tags:
+      - '*'
+    branches:
+      - 'master'
     paths:
       - '.github/workflows/**'
       - 'CMakeLists.txt'
@@ -91,8 +95,8 @@ jobs:
         run: |
           . /home/runner/python-env/sphinx/bin/activate
           if [ ${GITHUB_REPOSITORY} == 'atomvm/AtomVM' ]; then {
-            for remote in `git branch -r | grep -v "/HEAD\|${{ github.ref_name }}"`; do git checkout --track $remote; done
-            git switch ${{ github.ref_name }}
+            for remote in `git tag -l | grep -v "/HEAD\|${{ github.ref_name }}"`; do git checkout --track $remote; done
+            git checkout ${{ github.ref_name }}
           };
           fi
           mkdir build

doc/CMakeLists.txt

@@ -45,8 +45,11 @@ add_custom_target(edown-escript
     COMMENT "Preparing edown escript" VERBATIM
 )
 
-# Get branch name replacing any `/` with `-` in name for URLs.
-execute_process(COMMAND "bash" "-c" "sed -e 'y/\\//-/' <<< `git branch --show-current`" OUTPUT_VARIABLE BRANCH_NAME OUTPUT_STRIP_TRAILING_WHITESPACE)
+# Get the version tree name, tag if this is a tagged commit, otherwise master.
+execute_process(COMMAND "bash" "-c" "tag=$(git for-each-ref --points-at=HEAD --format='%(refname:lstrip=2)' refs/tags); ( [ $tag ] && echo $tag ) || echo 'master'"
+                OUTPUT_VARIABLE
+                DOC_TREE_VERSION
+                OUTPUT_STRIP_TRAILING_WHITESPACE )
 
 ##
 ## Erlang API documentation
@@ -120,17 +123,17 @@ if(SPHINX_FOUND)
     add_custom_target(sphinx-epub
         ${SPHINX_BUILD_EXECUTABLE} -D exclude_patterns=**/c_api_docs.rst,**/libatomvm/** -b epub -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/epub/
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-        COMMENT "Generating Sphinx PDF documentation" VERBATIM
+        COMMENT "Generating Sphinx EPub documentation" VERBATIM
         DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py
     )
 
     ## This target is intended for CI `Publish Docs` workflow.
     if ($ENV{CI})
         add_custom_target(GitHub_CI_Publish_Docs
-            COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_BINARY_DIR}/html /home/runner/work/AtomVM/AtomVM/www/doc/${BRANCH_NAME}
+            COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_BINARY_DIR}/html /home/runner/work/AtomVM/AtomVM/www/doc/${DOC_TREE_VERSION}
             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-            COMMENT "Copying html docs to publish location /home/runner/work/AtomVM/AtomVM/www/doc/${BRANCH_NAME}." VERBATIM
-            DEPENDS doc /home/runner/work/AtomVM/AtomVM/www/doc $ENV{BRANCH_NAME}
+            COMMENT "Copying html docs to publish location /home/runner/work/AtomVM/AtomVM/www/doc/${DOC_TREE_VERSION}." VERBATIM
+            DEPENDS doc /home/runner/work/AtomVM/AtomVM/www/doc $ENV{DOC_TREE_VERSION}
         )
     endif()
 
@@ -163,18 +166,18 @@ if (TARGET GitHub_CI_Publish_Docs)
 
     file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/pdf)
     add_custom_command(TARGET sphinx-pdf POST_BUILD
-        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/pdf/AtomVM-${BRANCH_NAME}.pdf ${CMAKE_CURRENT_BINARY_DIR}/html/pdf/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/pdf/AtomVM-${DOC_TREE_VERSION}.pdf ${CMAKE_CURRENT_BINARY_DIR}/html/pdf/
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/pdf
         COMMENT "Copying pdf to download location" VERBATIM
-        DEPENDS $ENV{BRANCH_NAME}
+        DEPENDS $ENV{DOC_TREE_VERSION}
     )
 
     file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/epub)
     add_custom_command(TARGET sphinx-epub POST_BUILD
-        COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/epub/AtomVM-${BRANCH_NAME}.epub" "${CMAKE_CURRENT_BINARY_DIR}/html/epub/"
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/epub/AtomVM-${DOC_TREE_VERSION}.epub ${CMAKE_CURRENT_BINARY_DIR}/html/epub/
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/epub
         COMMENT "Copying epub to download location." VERBATIM
-        DEPENDS $ENV{BRANCH_NAME}
+        DEPENDS $ENV{DOC_TREE_VERSION}
     )
 
     add_custom_command(TARGET sphinx-html POST_BUILD

doc/conf.py.in

@@ -140,11 +140,20 @@ html_context['display_lower_left'] = 'True'
 # SET CURRENT_VERSION
 from git import Repo
 repo = Repo( search_parent_directories=True )
-current_v = repo.active_branch.name
-if ("/" in current_v):
-    current_version = current_v.replace("/", "-")
+tag_list = sorted(repo.tags, key=lambda t: t.commit.committed_datetime)
+latest_tag = tag_list[-1]
+versions = list()
+for tag in tag_list:
+    versions.append(tag.name)
+
+versions.append('master')
+if ((repo.head.object.hexsha) == (latest_tag.commit.hexsha)):
+    current_version = latest_tag.name
 else:
-    current_version = current_v
+    current_version = 'master'
+
+print("Sphinx config found documentation candidates: %r." % (versions))
+print("Sphinx config current version: %r." % (current_version))
 
 # tell the theme which version we're currently on ('current_version' affects
 # the lower-left rtd menu and 'version' affects the logo-area version)
@@ -153,14 +162,7 @@ html_context['version'] = current_version
 
 # POPULATE LINKS TO OTHER VERSIONS
 html_context['versions'] = list()
-
-versions = [branch.name for branch in repo.branches]
-print("Sphinx config found repository branches: %r." % (versions))
-for add_version in versions:
-    if ("/" in add_version):
-        version = add_version.replace("/", "-")
-    else:
-        version = add_version
+for version in versions:
     html_context['versions'].append( (version, '/doc/' +version+ '/') )
 
 html_sidebars = {