Documentation updates

Various corrections, formatting fixes, updates, and visual enhancements to the generated documentation. Signed-off-by: Winford <winford@object.stream>
atomvm · Feb 1, 2024 · 34d5dc4 · 34d5dc4
1 parent 03a5190
commit 34d5dc4
Show file tree

Hide file tree

Showing 29 changed files with 2,920 additions and 1,815 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -14,7 +14,7 @@ AtomVM is open to any contribution.
 However before contributing, please read carefully our [Code of Conduct](CODE_OF_CONDUCT.md) and
 the following contribution guidelines.
 
-Please, also make sure to understand the [Apache 2.0 license](LICENSE.md) and the
+Please, also make sure to understand the [Apache 2.0 license](LICENSES/Apache-2.0.txt) and the
 [Developer Certificate of Origin](https://developercertificate.org/).
 
 Last but not least, **do not use GitHub issues for vulnerability reports**, read instead the
@@ -63,12 +63,11 @@ All source code modules should include copyright headers that are formatted for
     * SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
     */
 
-
 ### C Code
 
-C source code style is enforced with [clang-format-13](https://releases.llvm.org/13.0.1/tools/clang/docs/ClangFormat.html). To automatically fix a file, run:
+C source code style is enforced with [`clang-format-16`](https://releases.llvm.org/16.0.0/tools/clang/docs/ClangFormat.html). To automatically fix a file, run:
 
-    clang-format-13 --style=file -i file.c
+    clang-format-16 --style=file -i file.c
 
 #### Indentation
 
@@ -181,7 +180,7 @@ In the rare case that a function declaration and definition are both in differen
     }
     #endif /* DOXYGEN_SKIP_SECTION */
 
-> Note: You should include a short `/* comment */` trailing the `#ifndef` entry mentioning the file where the function is actually documented.
+>You should include a short `/* comment */` trailing the `#ifndef` entry mentioning the file where the function is actually documented.
 
 ### Erlang Code
 

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -22,22 +22,21 @@ project(doc)
 
 # Prepare souces in build directory
 include(${CMAKE_SOURCE_DIR}/CMakeModules/GetVersion.cmake)
-file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static)
-file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/edoc)
 file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/src DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)
 file(COPY ${CMAKE_SOURCE_DIR}/CONTRIBUTING.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src)
 file(COPY ${CMAKE_SOURCE_DIR}/CHANGELOG.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src)
 file(COPY ${CMAKE_SOURCE_DIR}/UPDATING.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src)
+file(COPY ${CMAKE_SOURCE_DIR}/CODE_OF_CONDUCT.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src)
+file(COPY ${CMAKE_SOURCE_DIR}/LICENSES/Apache-2.0.txt DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src/LICENSES)
+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/)
 
 # Configure libAtomVM restucturedtext skeleton.
-file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/files)
-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)
-foreach(SOURCE_TARGET ${SOURCE_FILES})
-    set(SOURCE_FILE ${SOURCE_TARGET})
-    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/apidocs/libatomvm/file.rst.in ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/files/${SOURCE_FILE}.rst @ONLY)
-endforeach(SOURCE_TARGET)
+file(GLOB SOURCE_FILES LIST_DIRECTORIES false RELATIVE ${CMAKE_SOURCE_DIR}/src/libAtomVM/ ${CMAKE_SOURCE_DIR}/src/libAtomVM/*.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)
 
 # Support for edoc -> markdown.
 add_custom_target(edown-escript
@@ -58,8 +57,14 @@ execute_process(COMMAND "bash" "-c" "tag=$(git for-each-ref --points-at=HEAD --f
 file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/erlang)
 file(COPY ${CMAKE_SOURCE_DIR}/libs/include DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/)
 
-foreach(ERLANG_LIB estdlib eavmlib alisp etest)
-    set(ERL_LIB ${ERLANG_LIB}) # to allow passing ERL_LIB to gendoc.erl.in
+set(ERLANG_LIBS
+    estdlib
+    eavmlib
+    alisp
+    etest
+)
+
+foreach(ERLANG_LIB ${ERLANG_LIBS})
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/edoc/gendoc.erl.in ${CMAKE_CURRENT_BINARY_DIR}/edoc/${ERLANG_LIB}/gendoc.erl @ONLY)
     file(COPY ${CMAKE_SOURCE_DIR}/libs/${ERLANG_LIB} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/)
     add_custom_target(edoc-${ERLANG_LIB}
@@ -82,7 +87,6 @@ set(DOT_FILES
 find_package(Graphviz)
 if(GRAPHVIZ_FOUND)
     message("Graphiz found")
-    file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/src/_static)
     foreach(DOT_FILE ${DOT_FILES})
         add_custom_command(
             OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg
@@ -91,7 +95,7 @@ if(GRAPHVIZ_FOUND)
             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
             COMMENT "Generating SVG for ${DOT_FILE}.dot" VERBATIM
         )
-        set(ERLANG_DOTFILE_TARGETS ${ERLANG_DOTFILE_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg)
+        set(DOTFILE_TARGETS ${DOTFILE_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg)
     endforeach()
 else()
     message("WARNING: Graphviz not found.  Some images may be missing in generated documentation.")
@@ -102,30 +106,31 @@ 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(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/libatomvm)
+    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}/)
+
     add_custom_target(sphinx-html
-        ${SPHINX_BUILD_EXECUTABLE} -b html -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/html/
+        ${SPHINX_BUILD_EXECUTABLE} -q -j auto -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 ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS}
+        DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS}
     )
 
     add_custom_target(sphinx-pdf
-        ${SPHINX_BUILD_EXECUTABLE} -D exclude_patterns=**/c_api_docs.rst,**/libatomvm/** -b rinoh -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/pdf/
+        ${SPHINX_BUILD_EXECUTABLE} -q -j auto -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 ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py
+        DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS}
     )
 
     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/
+        ${SPHINX_BUILD_EXECUTABLE} -q -j auto -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 ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py
+        DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS}
     )
 
     ## This target is intended for CI `Publish Docs` workflow.
@@ -143,17 +148,19 @@ else()
 endif()
 
 ## Fix URLs and change title to include "library" instead of "application"
-foreach(LIBAVM_ERL_LIB estdlib eavmlib alisp etest)
-    add_custom_command(TARGET edoc-${LIBAVM_ERL_LIB}
-        POST_BUILD
+foreach(LIBAVM_ERL_LIB ${ERLANG_LIBS})
+    add_custom_command(TARGET edoc-${LIBAVM_ERL_LIB} POST_BUILD
+        COMMAND find ./ -name *.md -exec sed -i -e "s/\#types/\#data-types/g" {} \;
+        COMMAND find ./ -name *.md -exec sed -i -e "s/\#index/\#function-index/g" {} \;
+        COMMAND find ./ -name *.md -exec sed -i -e "s/\#functions/\#function-details/g" {} \;
         COMMAND sed -i -e "s/\.md/\.html/g; s/application/library/g" ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/erlang/${LIBAVM_ERL_LIB}/README.md
-        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-        COMMENT "Fixing html link locations for ${LIBAVM_ERL_LIB}." VERBATIM
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/erlang/${LIBAVM_ERL_LIB}
+        COMMENT "Fixing links in ${LIBAVM_ERL_LIB} documentation." VERBATIM
     )
 endforeach(LIBAVM_ERL_LIB)
 
 add_custom_target(doc #ALL
-    DEPENDS ${ERLANG_EDOC_TARGETS} sphinx-html sphinx-pdf sphinx-epub
+    DEPENDS sphinx-html sphinx-pdf sphinx-epub
 )
 
 if (TARGET GitHub_CI_Publish_Docs)

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
@@ -736,7 +736,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
@@ -1110,7 +1110,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

diff --git a/doc/README.md b/doc/README.md
@@ -10,7 +10,7 @@ AtomVM documentation is built using the following tools:
 
 * Sphinx, for main HTML, PDF, and ePUB documentation
 * Doxygen, for AtomVMLib API documentation
-* Rebar3, for Erlang library documentation (requires active internet connection during build to retrieve tool dependancies)
+* Rebar3, for Erlang library documentation (requires active internet connection during build to retrieve tool dependencies)
 * Graphviz, for image generation
 
 Dependencies and make files are generated via the standard CMake tooling used in AtomVM builds.  However, the documentation sets are not built by default.  Instead, issue the following make targets after a CMake

diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -43,7 +43,7 @@ subprocess.call('doxygen Doxyfile', shell=True)
 import sphinx_rtd_theme
 
 project = 'AtomVM'
-copyright = '2017-2023, AtomVM'
+copyright = '2017-2024, AtomVM'
 author = 'github.com/atomvm'
 version = '@ATOMVM_BASE_VERSION@'
 release = '@ATOMVM_VERSION@'
@@ -57,16 +57,13 @@ extensions = [
     'breathe',
     'myst_parser',
     'sphinx_rtd_theme',
-    'sphinx.ext.graphviz',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.autosectionlabel',
-    'sphinx.ext.todo',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.inheritance_diagram'
+    'sphinx.ext.graphviz'
+]
+
+suppress_warnings = [
+    'epub.unknown_project_files',
+    'misc.highlighting_failure',
+    'toc.excluded'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -80,20 +77,32 @@ exclude_patterns = ['*/favicon/about.txt']
 # The master toctree document.
 master_doc = 'index'
 
-highlight_language = 'c'
+highlight_language = 'guess'
 primary_domain = 'c'
 
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'restructuredtext',
+    '.md': 'markdown'
+}
+
+# -- Sphinx Extension configuration ---------------------------------------------------
+
 # Breathe configuration
 breathe_projects = { "libatomvm": "@CMAKE_CURRENT_BINARY_DIR@/xml/" }
 breathe_default_project = "libatomvm"
 breathe_default_members = ('members', 'undoc-members')
+breathe_show_enumvalue_initializer = True
+breathe_show_define_initializer = True
+breathe_domain_by_extension = {
+    "h" : "c",
+    "c" : "c"
+}
+breathe_use_project_refids = True
 
-StandaloneHTMLBuilder.supported_image_types = [
-    'image/svg+xml',
-    'image/gif',
-    'image/png',
-    'image/jpeg'
-]
+myst_heading_anchors = 4
+myst_enable_extensions = ['colon_fence']
+myst_ref_domains = ['std', 'c', 'c.libAtomVM', 'c.*', 'default', 'null']
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -105,21 +114,34 @@ html_logo = '@CMAKE_CURRENT_SOURCE_DIR@/src/_static/avm_logo_banner.png'
 html_theme_options = {
     'logo_only': True,
     'style_external_links': True,
-    'display_version': True
+    'display_version': True,
+    'includehidden': False
 }
 
+StandaloneHTMLBuilder.supported_image_types = [
+    'image/svg+xml',
+    'image/gif',
+    'image/png',
+    'image/jpeg'
+]
+
 html_copy_source = False
 
+language = "en"
+html_meta = {
+    "description lang=en": "AtomVM Guides and API Documentation",
+    "keywords": "AtomVM, Erlang, Elixir, BEAM, IoT, embedded, ESP32, STM32, RP2040, Raspberry Pi Pico, WASM, libAtomVM, eavmlib, packbeam",
+    "property=og:locale": "en_US"
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['@CMAKE_CURRENT_BINARY_DIR@/src/_static']
 
-source_suffix = {
-    '.rst': 'restructuredtext',
-    '.txt': 'restructuredtext',
-    '.md': 'markdown',
-}
+html_css_files = [
+    'css/custom.css',
+]
 
 html_favicon = '@CMAKE_CURRENT_SOURCE_DIR@/src/_static/favicon/favicon.ico'
 
@@ -171,21 +193,26 @@ html_sidebars = {
     ],
 }
 
-# settings for creating PDF with rinoh
-rinoh_documents = [(
-  master_doc,
-  project+ '-' +current_version,
-  project+ ' Documentation',
-  '© ' +copyright,
+# 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') )
+
+# -- Options for PDF output -------------------------------------------------
+
+rinoh_documents = [dict(
+  doc=master_doc,
+  target=project+ '-' +current_version,
+  logo='@CMAKE_CURRENT_SOURCE_DIR@/src/_static/AtomVM-logo.png',
+  template='pdf_template.rtt'
 )]
+
 today_fmt = "%B %d, %Y"
 
-# settings for EPUB
-epub_tocdepth = 6
+# -- Options for EPUB output -------------------------------------------------
+
+epub_tocdepth = 3
 epub_show_urls = 'no'
 epub_basename = project+ '-' +current_version
 
-# 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') )
+
diff --git a/doc/edoc/gendoc.erl.in b/doc/edoc/gendoc.erl.in
@@ -30,7 +30,7 @@ main([LibraryName, SrcDir, TgtDir]) ->
     {ok, AllFiles} = file:list_dir(SrcDir),
     ErlFiles = [SrcDir ++ "/" ++ F || F <- AllFiles, ends_with(F, ".erl")],
     ok = edoc:application(
-        @ERL_LIB@,
+        @ERLANG_LIB@,
         ".",
         [
             {doclet, edown_doclet},
@@ -42,7 +42,7 @@ main([LibraryName, SrcDir, TgtDir]) ->
             {dir, TgtDir}
         ]
     ),
-    io:format("Generated documentation for application ~p using source files ~p into ~s~n", [
+    io:format("Generated documentation for library ~p using source files ~p into ~s~n", [
         LibraryName, ErlFiles, TgtDir
     ]).
 

diff --git a/doc/pdf_stylesheet.rts b/doc/pdf_stylesheet.rts
@@ -0,0 +1,10 @@
+# Copyright 2024 Winford (Uncle Grumpy) <winford@object.stream>
+#
+# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+
+[STYLESHEET]
+name = Restore section link names style sheet
+base = sphinx
+
+[linked reference]
+type = custom
diff --git a/doc/pdf_template.rtt b/doc/pdf_template.rtt
@@ -0,0 +1,8 @@
+# Copyright 2024 Winford (Uncle Grumpy) <winford@object.stream>
+#
+# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+
+[TEMPLATE_CONFIGURATION]
+name = PDF
+template = book
+stylesheet = pdf_stylesheet.rts