Skip to content

Commit 6382e1b

Browse files
UncleGrumpyUncleGrumpy
committed
Unify documentation theme
Changes the way doxgen documention in rendered for src/libatomvm. The final html output is created by the `sphinx` `breathe` extension so it can be rendered using the `read-the-docs` theme used be the rest of the documentation. Note: there is no automation yet for adding listings to the catagorized sections (including: functions, macros, types, and data structures), but the index and content for the individual source files will be generated automatically. The original `Doxygen` theme is still included and will always remain up to date. Signed-off-by: Winford <[email protected]>
1 parent 5e5039d commit 6382e1b

File tree

9 files changed

+234
-9
lines changed

9 files changed

+234
-9
lines changed

‎doc/CMakeLists.txt‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,20 @@
2121
project(doc)
2222

2323
# Prepare souces in build directory
24-
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html)
24+
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static)
2525
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/edoc)
2626
file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/src DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)
2727
file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/edoc/edown_dep DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/)
2828

29+
# Configure libAtomVM restucturedtext skeleton.
30+
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/files)
31+
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)
32+
foreach(SOURCE_TARGET ${SOURCE_FILES})
33+
set(SOURCE_FILE ${SOURCE_TARGET})
34+
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/apidocs/libatomvm/file.rst.in ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/files/${SOURCE_FILE}.rst @ONLY)
35+
endforeach(SOURCE_TARGET)
36+
37+
# Support for edoc -> markdown.
2938
add_custom_target(edown-escript
3039
COMMAND rebar3 get-deps co edown edoc && rebar3 escriptize edown edoc
3140
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/edoc/edown_dep
@@ -54,7 +63,6 @@ foreach(ERLANG_LIB estdlib eavmlib alisp etest)
5463
set(ERLANG_EDOC_TARGETS ${ERLANG_EDOC_TARGETS} edoc-${ERLANG_LIB})
5564
endforeach(ERLANG_LIB)
5665

57-
## TODO Uncomment when we incorporate Graphviz DOT files into documentation
5866
# ##
5967
# ## SVG files (from Graphviz dot files)
6068
# ##
@@ -101,14 +109,14 @@ if(SPHINX_FOUND)
101109
)
102110

103111
add_custom_target(sphinx-pdf
104-
${SPHINX_BUILD_EXECUTABLE} -b rinoh -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/pdf/
112+
${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/
105113
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
106114
COMMENT "Generating Sphinx PDF documentation" VERBATIM
107115
DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py
108116
)
109117

110118
add_custom_target(sphinx-epub
111-
${SPHINX_BUILD_EXECUTABLE} -b epub -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/epub/
119+
${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/
112120
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
113121
COMMENT "Generating Sphinx PDF documentation" VERBATIM
114122
DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py

‎doc/src/api-reference-documentation.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ estdlib
1818
---------------------
1919

2020
.. toctree::
21-
:maxdepth: 2
21+
:maxdepth: 1
2222
:glob:
2323

2424
apidocs/erlang/estdlib/*
@@ -28,7 +28,7 @@ eavmlib
2828
---------------------
2929

3030
.. toctree::
31-
:maxdepth: 2
31+
:maxdepth: 1
3232
:glob:
3333

3434
apidocs/erlang/eavmlib/*
@@ -38,7 +38,7 @@ alisp
3838
---------------------
3939

4040
.. toctree::
41-
:maxdepth: 2
41+
:maxdepth: 1
4242
:glob:
4343

4444
apidocs/erlang/alisp/*
@@ -48,7 +48,7 @@ etest
4848
---------------------
4949

5050
.. toctree::
51-
:maxdepth: 2
51+
:maxdepth: 1
5252
:glob:
5353

5454
apidocs/erlang/etest/*
@@ -62,4 +62,4 @@ AtomVM 'C' Internal Libraries
6262

6363
c_api_docs
6464

65-
[`libAtomVM <apidocs/libatomvm/index.html>`_]
65+
[`libAtomVM (Doxygen theme) <_static/libatomvm/index.html>`_]

‎doc/src/apidocs/libatomvm/data_structures.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.. Copyright 2023 Winford (Uncle Grumpy) <[email protected]>
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
4+
5+
---------------------
6+
Data Strucures
7+
---------------------
8+
.. toctree::
9+
:maxdepth: 3
10+
:caption: Structs
11+
12+
.. doxygenstruct:: AtomStringIntPair
13+
14+
.. doxygenstruct:: CContext
15+
16+
.. toctree::
17+
:maxdepth: 3
18+
:caption: Enums
19+
20+
.. doxygenenum::

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
2+
.. Copyright 2023 Winford (Uncle Grumpy) <[email protected]>
3+
..
4+
.. SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
5+
6+
------------------
7+
@SOURCE_FILE@
8+
------------------
9+
.. toctree::
10+
:maxdepth: 3
11+
12+
.. doxygenfile:: @SOURCE_FILE@
13+
:outline:
14+
:allow-dot-graphs:

‎doc/src/apidocs/libatomvm/functions.rst‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
.. Copyright 2023 Winford (Uncle Grumpy) <[email protected]>
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
4+
5+
---------------------
6+
Functions
7+
---------------------
8+
.. toctree::
9+
:maxdepth: 3
10+
:caption: Functions
11+
12+
.. doxygenfunction:: atom_are_equals
13+
.. doxygenfunction:: atom_string_to_c
14+
.. doxygenfunction:: atom_write_mfa
15+
.. doxygenfunction:: avmpack_find_section_by_flag
16+
.. doxygenfunction:: avmpack_find_section_by_name
17+
.. doxygenfunction:: avmpack_fold
18+
.. doxygenfunction:: avmpack_is_valid
19+
.. doxygenfunction:: context_destroy
20+
.. doxygenfunction:: context_execute_loop
21+
.. doxygenfunction:: context_message_queue_len
22+
.. doxygenfunction:: context_new
23+
.. doxygenfunction:: context_size
24+
.. doxygenfunction:: debug_dump_context
25+
.. doxygenfunction:: debug_dump_heap
26+
.. doxygenfunction:: debug_dump_memory
27+
.. doxygenfunction:: debug_dump_registers
28+
.. doxygenfunction:: debug_dump_stack
29+
.. doxygenfunction:: debug_print_processes_list
30+
.. doxygenfunction:: externalterm_from_binary
31+
.. doxygenfunction:: externalterm_to_binary
32+
.. doxygenfunction:: externalterm_to_term
33+
.. doxygenfunction:: globalcontext_atomstring_from_term
34+
.. doxygenfunction:: globalcontext_destroy
35+
.. doxygenfunction:: globalcontext_existing_term_from_atom_string
36+
.. doxygenfunction:: globalcontext_get_module
37+
.. doxygenfunction:: globalcontext_get_new_process_id
38+
.. doxygenfunction:: globalcontext_get_process
39+
.. doxygenfunction:: globalcontext_get_registered_process
40+
.. doxygenfunction:: globalcontext_insert_atom
41+
.. doxygenfunction:: globalcontext_insert_atom_maybe_copy
42+
.. doxygenfunction:: globalcontext_insert_module
43+
.. doxygenfunction:: globalcontext_is_atom_index_equal_to_atom_string
44+
.. doxygenfunction:: globalcontext_new
45+
.. doxygenfunction:: globalcontext_register_process
46+
.. doxygenfunction:: globalcontext_unregister_process
47+
.. doxygenfunction:: iff_is_valid_beam
48+
.. doxygenfunction:: mailbox_dequeue
49+
.. doxygenfunction:: mailbox_destroy_message
50+
.. doxygenfunction:: mailbox_peek
51+
.. doxygenfunction:: mailbox_receive
52+
.. doxygenfunction:: mailbox_remove
53+
.. doxygenfunction:: mailbox_send
54+
.. doxygenfunction:: module_load_literal
55+
.. doxygenfunction:: module_new_from_iff_binary
56+
.. doxygenfunction:: module_resolve_function
57+
.. doxygenfunction:: module_search_exported_function
58+
.. doxygenfunction:: reg_type_c
59+
.. doxygenfunction:: scan_iff
60+
.. doxygenfunction:: scheduler_make_ready
61+
.. doxygenfunction:: scheduler_make_waiting
62+
.. doxygenfunction:: scheduler_next
63+
.. doxygenfunction:: scheduler_set_timeout
64+
.. doxygenfunction:: scheduler_terminate
65+
.. doxygenfunction:: scheduler_wait
66+
.. doxygenfunction:: schudule_processes_count
67+
.. doxygenfunction:: sys_consume_pending_events
68+
.. doxygenfunction:: sys_create_port
69+
.. doxygenfunction:: sys_get_info
70+
.. doxygenfunction:: sys_load_module
71+
.. doxygenfunction:: sys_monotonic_time
72+
.. doxygenfunction:: sys_time
73+
.. doxygenfunction:: term_alloc_refc_binary
74+
.. doxygenfunction:: term_alloc_sub_binary
75+
.. doxygenfunction:: term_compare
76+
.. doxygenfunction:: term_display
77+
.. doxygenfunction:: term_fprint
78+
.. doxygenfunction:: term_funprint
79+
.. doxygenfunction:: term_snprint

‎doc/src/apidocs/libatomvm/index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. Copyright 2023 Winford (Uncle Grumpy) <[email protected]>
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
4+
5+
---------------------
6+
libAtomVM Index
7+
---------------------
8+
.. toctree::
9+
:maxdepth: 3
10+
11+
.. doxygenindex::
12+
:project: libatomvm
13+
:outline:
14+
:allow-dot-graphs:

‎doc/src/apidocs/libatomvm/macros.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
.. Copyright 2023 Winford (Uncle Grumpy) <[email protected]>
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
4+
5+
---------------------
6+
MACROS
7+
---------------------
8+
.. toctree::
9+
:maxdepth: 3
10+
11+
.. doxygendefine:: AT8U
12+
13+
.. doxygendefine:: ATOM_STR
14+
15+
.. doxygendefine:: CODE
16+
17+
.. doxygendefine:: EXPT
18+
19+
.. doxygendefine:: FUNT
20+
21+
.. doxygendefine:: GET_LIST_ENTRY
22+
23+
.. doxygendefine:: IFF_SECTION_HEADER_SIZE
24+
25+
.. doxygendefine:: IMPT
26+
27+
.. doxygendefine:: LINT
28+
29+
.. doxygendefine:: LITT
30+
31+
.. doxygendefine:: LITU
32+
33+
.. doxygendefine:: LOCT
34+
35+
.. doxygendefine:: MAX_OFFS
36+
37+
.. doxygendefine:: MAX_SIZES
38+
39+
.. doxygendefine:: STRT

‎doc/src/apidocs/libatomvm/types.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. Copyright 2023 Winford (Uncle Grumpy) <[email protected]>
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
4+
5+
---------------------
6+
Types
7+
---------------------
8+
.. toctree::
9+
:maxdepth: 3
10+
:caption: Types
11+
12+
.. doxygentypedef:: avmpack_fold_fun
13+
14+
.. doxygentypedef:: CContext
15+
16+
.. doxygentypedef:: term
17+
18+
.. doxygentypedef:: term_ref

‎doc/src/c_api_docs.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
.. Copyright 2023 Winford (Uncle Grumpy) <[email protected]>
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
4+
5+
-------------------------
6+
libAtomVM
7+
-------------------------
8+
9+
[`libAtomVM (Doxygen theme) <_static/libatomvm/index.html>`_]
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: C Library APIs
14+
15+
apidocs/libatomvm/data_structures
16+
apidocs/libatomvm/types
17+
apidocs/libatomvm/macros
18+
apidocs/libatomvm/functions
19+
20+
-------------------------
21+
libAtomVM Source Files
22+
-------------------------
23+
24+
.. toctree::
25+
:maxdepth: 2
26+
:glob:
27+
28+
apidocs/libatomvm/files/*
29+
30+
.. toctree::
31+
:maxdepth: 2
32+
33+
apidocs/libatomvm/index

0 commit comments

Comments
 (0)