Documentation updates

Various corrections, formatting fixes, updates, and visual enhancements to the generated documentation. Signed-off-by: Winford <[email protected]>
UncleGrumpy · Jan 30, 2024 · d3676d7 · d3676d7
1 parent 6cbaa98
commit d3676d7
Show file tree

Hide file tree

Showing 32 changed files with 2,438 additions and 1,160 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
@@ -173,15 +173,20 @@ C source modules (`.c`) should be organized as follows:
 
 In the rare case that a function declaration and definition are both in different header files (rather than the definition in a `*.c` file) this can cause rendering errors for `Doxygen`. The work around for these cases can be demonstrated with this example for the function `sys_listener_destroy` it is documented and declared in `sys.h` and defined as follows in `listeners.h`:
 
+```c
     #ifndef DOXYGEN_SKIP_SECTION /* documented in sys.h */
     void sys_listener_destroy(struct ListHead *item)
     {
         EventListener *listener = GET_LIST_ENTRY(item, EventListener, listeners_list_head);
         free(listener);
     }
     #endif /* DOXYGEN_SKIP_SECTION */
+```
 
-> Note: You should include a short `/* comment */` trailing the `#ifndef` entry mentioning the file where the function is actually documented.
+```{admonition} Note:
+   :class: note
+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
@@ -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}
     )
 
     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 ${ERLANG_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 ${ERLANG_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,22 +114,31 @@ 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_favicon = '@CMAKE_CURRENT_SOURCE_DIR@/src/_static/favicon/favicon.ico'
 
 html_baseurl = 'https://atomvm.net/doc'
@@ -171,21 +189,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) <[email protected]>
+#
+# 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) <[email protected]>
+#
+# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+
+[TEMPLATE_CONFIGURATION]
+name = PDF
+template = book
+stylesheet = pdf_stylesheet.rts