Publish documentation for branches and tags

These changes will allow publishing documentation for branches (in addition to
`main`, which is already published), while continuing to support publishing for
release tags. The menu listing for `main` has been enhanced to show the link as
`main branch (unstable)`, other branch names will appear as (unreleased), like:
`release-0.6 branch (unreleased)`. The appearance of links to (tagged) released
versions of the documentation are unchanged. This should make it easy for users
to identify the correct version of the documentation, and not mistake
`release-0.6` for a stable 0.6 release version of the documentation, and easily
identify the docs version that matches a branch they are interested in working
on, by differentiating branch versions of the documentation.

Signed-off-by: Winford <winford@object.stream>

doc/CMakeLists.txt

@@ -46,11 +46,29 @@ add_custom_target(edown-escript
     COMMENT "Preparing edown escript" VERBATIM
 )
 
-# Get the version tree name, tag if this is a tagged commit, otherwise main.
-execute_process(COMMAND "bash" "-c" "tag=$(git for-each-ref --points-at=HEAD --format='%(refname:lstrip=2)' refs/tags); ( [ $tag ] && echo $tag ) || echo 'main'"
-                OUTPUT_VARIABLE
-                DOC_TREE_VERSION
-                OUTPUT_STRIP_TRAILING_WHITESPACE )
+# Get the version tree name, tag if this is a tagged commit, otherwise get the current branch name.
+if ($ENV{CI})
+    if (NOT (DEFINED ENV{GITHUB_BASE_REF}) AND ($ENV{GITHUB_REPOSITORY} STREQUAL "atomvm/AtomVM"))
+        set(DOC_TREE_VERSION $ENV{GITHUB_REF_NAME})
+        message("CI Publishing documentation for ${DOC_TREE_VERSION}")
+    elif ($ENV{GITHUB_REPOSITORY} STREQUAL "atomvm/AtomVM")
+        set(DOC_TREE_VERSION "ci-test-build")
+        message("CI Test building documentation on ${DOC_TREE_VERSION}")
+    else()
+        set(DOC_TREE_VERSION $ENV{GITHUB_REF_NAME})
+        message("CI Test building documentation on ${DOC_TREE_VERSION}")
+    endif (NOT (DEFINED ENV{GITHUB_BASE_REF}) AND ($ENV{GITHUB_REPOSITORY} STREQUAL "atomvm/AtomVM"))
+else()
+    execute_process(COMMAND "bash" "-c" "tag=$(git for-each-ref --points-at=HEAD --format='%(refname:lstrip=2)' refs/tags); ( [ $tag ] && echo $tag )|| git branch --show-current"
+                    OUTPUT_VARIABLE
+                    DOC_TREE_VERSION
+                    OUTPUT_STRIP_TRAILING_WHITESPACE )
+    message("Local documentation test build on ${DOC_TREE_VERSION}")
+endif($ENV{CI})
+
+
+## conf.py.in must be configured after DOC_TREE_VERSION is defined
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
 
 ##
 ## Erlang API documentation
@@ -108,7 +126,6 @@ endif()
 find_package(Sphinx)
 if(SPHINX_FOUND)
     message("Sphinx found: ${SPHINX_BUILD_EXECUTABLE}")
-    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
     file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/pdf_stylesheet.rts DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)
     file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/pdf_template.rtt DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)

doc/conf.py.in

@@ -164,14 +164,26 @@ repo = Repo( search_parent_directories=True )
 tag_list = sorted(repo.tags, key=lambda t: t.commit.committed_datetime)
 latest_tag = tag_list[-1]
 versions = list()
+release_list = list()
 for tag in tag_list:
     versions.append(tag.name)
+    release_list.append(tag.name)
+
+omit_branch_list = ('release-0.5')
+branch_list = sorted(repo.branches, key=lambda t: t.commit.committed_datetime)
+for branch in branch_list:
+    if branch.name not in omit_branch_list:
+        versions.append(branch.name)
 
-versions.append('main')
 if ((repo.head.object.hexsha) == (latest_tag.commit.hexsha)):
     current_version = latest_tag.name
+    download_version = current_version
 else:
-    current_version = 'main'
+    download_version = '@DOC_TREE_VERSION@'
+    if ((download_version) == ('main')):
+        current_version = download_version + ' branch (unstable)'
+    else:
+        current_version = download_version + ' branch (unreleased)'
 
 print("Sphinx config found documentation candidates: %r." % (versions))
 print("Sphinx config current version: %r." % (current_version))
@@ -184,7 +196,13 @@ html_context['version'] = current_version
 # POPULATE LINKS TO OTHER VERSIONS
 html_context['versions'] = list()
 for version in versions:
-    html_context['versions'].append( (version, '/doc/' +version+ '/') )
+    if ((version) == ('main')):
+        html_context['versions'].append( (version + ' branch (unstable)', '/doc/' +version+ '/') )
+    else:
+        if (version not in release_list):
+            html_context['versions'].append( (version + ' branch (unreleased)', '/doc/' +version+ '/') )
+        else:
+            html_context['versions'].append( (version, '/doc/' +version+ '/') )
 
 html_sidebars = {
     '**': [
@@ -194,14 +212,14 @@ html_sidebars = {
 
 # POPULATE LINKS TO OTHER FORMATS/DOWNLOADS
 html_context['downloads'] = list()
-html_context['downloads'].append( ('pdf', '/doc/' +current_version+ '/pdf/' +project+ '-' +current_version+ '.pdf') )
-html_context['downloads'].append( ('epub', '/doc/' +current_version+ '/epub/' +project+ '-' +current_version+ '.epub') )
+html_context['downloads'].append( ('pdf', '/doc/' +download_version+ '/pdf/' +project+ '-' +download_version+ '.pdf') )
+html_context['downloads'].append( ('epub', '/doc/' +download_version+ '/epub/' +project+ '-' +download_version+ '.epub') )
 
 # -- Options for PDF output -------------------------------------------------
 
 rinoh_documents = [dict(
   doc=master_doc,
-  target=project+ '-' +current_version,
+  target=project+ '-' +download_version,
   logo='@CMAKE_CURRENT_SOURCE_DIR@/src/_static/AtomVM-logo.png',
   template='pdf_template.rtt'
 )]
@@ -212,4 +230,4 @@ today_fmt = "%B %d, %Y"
 
 epub_tocdepth = 3
 epub_show_urls = 'no'
-epub_basename = project+ '-' +current_version
+epub_basename = project+ '-' +download_version