Merge pull request #1239 from UncleGrumpy/docs_build-configs_warnings

Docs build config changes to address warnings and improve rendering

The combined effect of these changes greatly reduces the number of warning
emitted when building the documentation, and improve some rendering. Several
more source files are omitted from the documentation build process that do not
add any information to the documentation but confuse the build system leading
to many warnings and some rendering errors. There are notes in each commit
about the various configuration changes.

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

doc/CMakeLists.txt

@@ -32,12 +32,22 @@ file(COPY ${CMAKE_SOURCE_DIR}/LICENSES/Apache-2.0.txt DESTINATION ${CMAKE_CURREN
 file(COPY ${CMAKE_SOURCE_DIR}/SECURITY.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src)
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/release-notes.md.in ${CMAKE_CURRENT_BINARY_DIR}/src/release-notes.md @ONLY)
 file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/edoc/edown_dep DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/)
+target_compile_definitions(libAtomVM PUBLIC AVM_TASK_DRIVER_ENABLED)
 
 # Configure libAtomVM restucturedtext skeleton.
 file(GLOB SOURCE_FILES LIST_DIRECTORIES false RELATIVE ${CMAKE_SOURCE_DIR}/src/libAtomVM/ ${CMAKE_SOURCE_DIR}/src/libAtomVM/*.c ${CMAKE_SOURCE_DIR}/src/libAtomVM/*.h)
+set(OMIT_FILES
+    "defaultatoms.c"
+    "opcodesswitch.h"
+    "scheduler.c"
+    "tempstack.h"
+)
 foreach(SOURCE_FILE ${SOURCE_FILES})
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/apidocs/libatomvm/file.rst.in ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/src/${SOURCE_FILE}.rst @ONLY)
 endforeach(SOURCE_FILE)
+foreach(OMIT ${OMIT_FILES})
+    file(REMOVE ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/src/${OMIT}.rst)
+endforeach(OMIT)
 
 # Support for edoc -> markdown.
 add_custom_target(edown-escript

doc/Doxyfile.in

@@ -465,7 +465,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,
@@ -520,7 +520,7 @@ HIDE_FRIEND_COMPOUNDS  = NO
 # blocks will be appended to the function's detailed documentation block.
 # The default value is: NO.
 
-HIDE_IN_BODY_DOCS      = NO
+HIDE_IN_BODY_DOCS      = YES
 
 # The INTERNAL_DOCS tag determines if documentation that is typed after a
 # \internal command is included. If the tag is set to NO then the documentation
@@ -692,7 +692,7 @@ SHOW_FILES             = YES
 # Folder Tree View (if specified).
 # The default value is: YES.
 
-SHOW_NAMESPACES        = YES
+SHOW_NAMESPACES        = NO
 
 # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 # doxygen should invoke to get the current version for each file (typically from
@@ -769,7 +769,7 @@ WARN_IF_DOC_ERROR      = YES
 # EXTRACT_ALL is set to YES then this flag will automatically be disabled.
 # The default value is: NO.
 
-WARN_NO_PARAMDOC       = NO
+WARN_NO_PARAMDOC       = YES
 
 # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
 # a warning is encountered.
@@ -903,7 +903,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */libAtomVM/opcodesswitch.h
+EXCLUDE_PATTERNS = */defaultatoms.c */opcodesswitch.h */scheduler.c */tempstack.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1015,7 +1015,7 @@ SOURCE_BROWSER         = YES
 # classes and enums directly into the documentation.
 # The default value is: NO.
 
-INLINE_SOURCES         = NO
+INLINE_SOURCES         = YES
 
 # Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any
 # special comment blocks from generated source code fragments. Normal C, C++ and
@@ -2030,7 +2030,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2070,7 +2070,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = DOXYGEN_SKIP_SECTION
+PREDEFINED = DOXYGEN_SKIP_SECTION AVM_TASK_DRIVER_ENABLED ENABLE_ADVANCED_TRACE OTP_SOCKET_LWIP
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -2316,7 +2316,7 @@ DOT_IMAGE_FORMAT       = png
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INTERACTIVE_SVG        = NO
+INTERACTIVE_SVG        = YES
 
 # The DOT_PATH tag can be used to specify the path where the dot tool can be
 # found. If left blank, it is assumed the dot tool can be found in the path.

doc/conf.py.in

@@ -63,7 +63,9 @@ extensions = [
 suppress_warnings = [
     'epub.unknown_project_files',
     'misc.highlighting_failure',
-    'toc.excluded'
+    'toc.excluded',
+    'myst.*',
+    'breathe.*'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/pdf_stylesheet.rts

@@ -8,3 +8,6 @@ base = sphinx
 
 [linked reference]
 type = custom
+
+[chapter]
+page_break = any

doc/src/apidocs/libatomvm/file.rst.in

@@ -5,6 +5,7 @@
 :orphan:
 
 .. c:namespace:: libAtomVM
+.. c:namespace-push:: @SOURCE_FILE@
 
 ------------------
 @SOURCE_FILE@