From 283e63939319736b8b21703d18b764a90d8d34b3 Mon Sep 17 00:00:00 2001 From: Winford Date: Sun, 4 Aug 2024 19:44:29 -0700 Subject: [PATCH] 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 --- doc/CMakeLists.txt | 29 +++++++++++++++++++++++------ doc/conf.py.in | 32 +++++++++++++++++++++++++------- 2 files changed, 48 insertions(+), 13 deletions(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index ba2365c5a..9e256fd6a 100644 --- a/doc/CMakeLists.txt +++ b/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 for $ENV{GITHUB_REPOSITORY} on branch ${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}/) diff --git a/doc/conf.py.in b/doc/conf.py.in index 0682befc6..17234206d 100644 --- a/doc/conf.py.in +++ b/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