Merge pull request #1499 from UncleGrumpy/fix-publish-docs

Changes to reduce the size of published documentation on GitHub Pages

These changes take the first steps necessary to remove older and pre-release
versions from the published documentation by removing these versions form the
navigation menu. This directs users to recent stable releases, and helps keep
the published pages below the 1 GB limit for GitHub hosted Pages branches.

Note: the old documentation versions will be removed from the atomvm_www
Production branch in a PR to that repo.

Minor adjustment to graphics format from png to svg to keep sizes smaller and
render better on a wider variety of browsers, and improve the quality of the
PDF ans epub documents.

Changes to where build artifacts are created to keep them from polluting the
published content and consuming unnecessary space.

Adds a missing check for doxgen before attempting to build the documentation.

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

Author: bettio

.github/workflows/publish-docs.yaml

@@ -129,7 +129,7 @@ jobs:
           git add "doc/${{ github.ref_name }}"
           git add .
           git diff --exit-code Production || echo "Going to commit"
-          git diff --exit-code Production || git commit -m "Update Documentation"
+          git diff --exit-code Production || git commit -m "Update Documentation for ${{ github.ref_name }}"
           git log -1
       - name: Push changes
         if: github.repository == 'atomvm/AtomVM'

CMakeModules/FindDoxygen.cmake

@@ -0,0 +1,28 @@
+#
+# This file is part of AtomVM.
+#
+# Copyright 2021 Fred Dushin <fred@dushin.net>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+#
+
+find_program(DOXYGEN_PATH doxygen)
+
+if (DOXYGEN_PATH)
+    set(DOXYGEN_FOUND TRUE)
+    set(DOXYGEN_BUILD_EXECUTABLE "${DOXYGEN_PATH}")
+elseif(DOXYGEN_FIND_REQUIRED)
+    message(FATAL_ERROR "Doxygen command (doxygen) not found")
+endif()

doc/CMakeLists.txt

@@ -126,27 +126,30 @@ endif()
 ##
 find_package(Sphinx)
 if(SPHINX_FOUND)
+  find_package(Doxygen)
+  if(DOXYGEN_FOUND)
+    message("Doxygen found: ${DOXYGEN_BUILD_EXECUTABLE}")
     message("Sphinx found: ${SPHINX_BUILD_EXECUTABLE}")
     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}/)
     file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/libatomvm)
     add_custom_target(sphinx-html
-        ${SPHINX_BUILD_EXECUTABLE} -q -b html -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/html/
+        ${SPHINX_BUILD_EXECUTABLE} -q --doctree-dir ${CMAKE_CURRENT_BINARY_DIR}/doctree -b html -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/html/
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         COMMENT "Generating Sphinx HTML documentation" VERBATIM
         DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS}
     )
 
     add_custom_target(sphinx-pdf
-        ${SPHINX_BUILD_EXECUTABLE} -q -D exclude_patterns=apidocs/libatomvm/** -b rinoh -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/pdf/
+        ${SPHINX_BUILD_EXECUTABLE} -q --doctree-dir ${CMAKE_CURRENT_BINARY_DIR}/doctree -D exclude_patterns=apidocs/libatomvm/** -b rinoh -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/pdf/
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         COMMENT "Generating Sphinx PDF documentation" VERBATIM
         DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS}
     )
 
     add_custom_target(sphinx-epub
-        ${SPHINX_BUILD_EXECUTABLE} -q -D exclude_patterns=apidocs/libatomvm/**,LICENSES/** -b epub -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/epub/
+        ${SPHINX_BUILD_EXECUTABLE} -q --doctree-dir ${CMAKE_CURRENT_BINARY_DIR}/doctree -D exclude_patterns=apidocs/libatomvm/**,LICENSES/** -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 EPub documentation" VERBATIM
         DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS}
@@ -162,6 +165,9 @@ if(SPHINX_FOUND)
         )
     endif()
 
+  else()
+    message("Unable to find Doxygen -- no Sphinx documentation will be generated")
+  endif()
 else()
     message("Unable to find Sphinx -- no Sphinx documentation will be generated")
 endif()

doc/Doxyfile.in

@@ -2304,7 +2304,7 @@ DIRECTORY_GRAPH        = YES
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.

doc/conf.py.in

@@ -60,6 +60,8 @@ extensions = [
     'sphinx.ext.graphviz'
 ]
 
+graphviz_output_format = 'svg'
+
 suppress_warnings = [
     'epub.unknown_project_files',
     'misc.highlighting_failure',
@@ -167,9 +169,11 @@ tag_list = sorted(repo.tags, key=lambda t: t.commit.committed_datetime)
 latest_tag = tag_list[-1]
 versions = list()
 release_list = list()
+omit_tag_list = [ 'v0.6.0-alpha.0', 'v0.6.0-alpha.1', 'v0.6.0-alpha.2', 'v0.6.0-beta.0', 'v0.6.0-beta.1', 'v0.6.0-rc.0' ]
 for tag in tag_list:
-    versions.append(tag.name)
-    release_list.append(tag.name)
+    if tag.name not in omit_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)