Skip to content

Commit a43aa52

Browse files
fadushinfadushin
authored
Merge pull request atomvm#524 from UncleGrumpy/publish_docs
Documentation enhancements
2 parents 1549382 + 26f4f63 commit a43aa52

35 files changed

+1020
-102
lines changed

‎.github/workflows/publish-docs.yaml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
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+
# This is a workflow for atomvm/AtomVM to Publish API documentation and other content from the `doc` directory to
7+
# atomvm.net hosted on GitHub Pages
8+
9+
name: Publish Docs
10+
11+
# Controls when the workflow will run
12+
on:
13+
# Triggers the workflow on push request events for all branches
14+
push:
15+
16+
# Allows you to run this workflow manually from the Actions tab
17+
workflow_dispatch:
18+
19+
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
20+
jobs:
21+
# This workflow contains a single job called "build"
22+
build:
23+
# The type of runner that the job will run on
24+
runs-on: ubuntu-latest
25+
26+
# Steps represent a sequence of tasks that will be executed as part of the job
27+
steps:
28+
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
29+
30+
- name: Install Deps
31+
run: |
32+
sudo apt update -y
33+
DEBIAN_FRONTEND=noninteractive sudo apt install -y git cmake doxygen graphviz python3-pip python3-virtualenv python3-setuptools python3-stemmer wget
34+
35+
- uses: actions/cache@v3
36+
id: sphinx-cache
37+
with:
38+
path: /home/runner/python-env/sphinx
39+
key: ${{ runner.os }}-sphinx-install
40+
41+
- name: Install Sphinx
42+
if: steps.cache.outputs.sphinx-cache-hit != 'true'
43+
run: |
44+
python3 -m venv /home/runner/python-env/sphinx
45+
. /home/runner/python-env/sphinx/bin/activate
46+
python3 -m pip install sphinx
47+
python3 -m pip install myst-parser
48+
python3 -m pip install sphinx-rtd-theme
49+
python3 -m pip install rinohtype
50+
python3 -m pip install pillow
51+
python3 -m pip install gitpython
52+
python3 -m pip install breathe
53+
python3 -m pip install pygments
54+
55+
- uses: erlef/setup-beam@v1
56+
with:
57+
otp-version: "24"
58+
elixir-version: "1.14"
59+
60+
- name: Install rebar3
61+
working-directory: /tmp
62+
run: |
63+
wget https://s3.amazonaws.com/rebar3/rebar3 && chmod +x rebar3
64+
./rebar3 local install
65+
echo "/home/runner/.cache/rebar3/bin" >> ${GITHUB_PATH}
66+
67+
- uses: erlef/setup-beam@v1
68+
with:
69+
otp-version: "24"
70+
elixir-version: "1.14"
71+
72+
- uses: actions/checkout@v3
73+
with:
74+
repository: atomvm/AtomVM
75+
fetch-depth: 0
76+
77+
- uses: actions/checkout@v3
78+
id: checkout-production
79+
with:
80+
repository: atomvm/atomvm_www
81+
ref: Production
82+
path: /home/runner/work/AtomVM/AtomVM/www
83+
84+
- name: Build Site
85+
run: |
86+
. /home/runner/python-env/sphinx/bin/activate
87+
for remote in `git branch -r | grep -v /HEAD | grep -v ${{ github.ref_name }}`; do git checkout --track $remote; done
88+
git switch ${{ github.ref_name }}
89+
git branch
90+
mkdir build
91+
cd build
92+
cmake ..
93+
cd doc
94+
make GitHub_CI_Publish_Docs
95+
96+
- name: Commit files
97+
working-directory: /home/runner/work/AtomVM/AtomVM/www
98+
run: |
99+
git checkout Production
100+
git config --local user.email "[email protected]"
101+
git config --local user.name "AtomVM Doc Bot"
102+
git add .
103+
git commit -m "Update Documentation"
104+
- name: Push changes
105+
working-directory: /home/runner/work/AtomVM/AtomVM/www
106+
run: |
107+
eval `ssh-agent -t 60 -s`
108+
echo "${{ secrets.PUBLISH_ACTION_KEY }}" | ssh-add -
109+
mkdir -p ~/.ssh/
110+
ssh-keyscan github.com >> ~/.ssh/known_hosts
111+
git remote add push_dest "[email protected]:atomvm/atomvm_www.git"
112+
git fetch push_dest
113+
git push --set-upstream push_dest Production
114+

‎doc/CMakeLists.txt‎

Lines changed: 114 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -20,66 +20,73 @@
2020

2121
project(doc)
2222

23-
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html)
23+
# Prepare souces in build directory
24+
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static)
25+
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/edoc)
26+
file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/src DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)
27+
file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/edoc/edown_dep DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/)
28+
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.
38+
add_custom_target(edown-escript
39+
COMMAND rebar3 get-deps co edown edoc && rebar3 escriptize edown edoc
40+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/edoc/edown_dep
41+
COMMENT "Preparing edown escript" VERBATIM
42+
)
43+
44+
# Get branch name
45+
execute_process(COMMAND git branch --show-current OUTPUT_VARIABLE BRANCH_NAME OUTPUT_STRIP_TRAILING_WHITESPACE)
2446

2547
##
2648
## Erlang API documentation
2749
##
2850
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/erlang)
51+
file(COPY ${CMAKE_SOURCE_DIR}/libs/include DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/)
52+
2953
foreach(ERLANG_LIB estdlib eavmlib alisp etest)
30-
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/erlang/${ERLANG_LIB})
54+
set(ERL_LIB ${ERLANG_LIB}) # to allow passing ERL_LIB to gendoc.erl.in
55+
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/edoc/gendoc.erl.in ${CMAKE_CURRENT_BINARY_DIR}/edoc/${ERLANG_LIB}/gendoc.erl @ONLY)
56+
file(COPY ${CMAKE_SOURCE_DIR}/libs/${ERLANG_LIB} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/)
3157
add_custom_target(edoc-${ERLANG_LIB}
32-
COMMAND escript ${CMAKE_SOURCE_DIR}/tools/doc/gendoc.erl ${ERLANG_LIB} ${CMAKE_SOURCE_DIR}/libs/${ERLANG_LIB}/src ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/erlang/${ERLANG_LIB}
33-
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
34-
COMMENT "Generating edoc for ${ERLANG_LIB}"
35-
VERBATIM
58+
COMMAND escript gendoc.erl ${ERLANG_LIB} src ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/erlang/${ERLANG_LIB}
59+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/edoc/${ERLANG_LIB}
60+
COMMENT "Generating edoc markdown for ${ERLANG_LIB}" VERBATIM
61+
DEPENDS edown-escript
3662
)
3763
set(ERLANG_EDOC_TARGETS ${ERLANG_EDOC_TARGETS} edoc-${ERLANG_LIB})
3864
endforeach(ERLANG_LIB)
3965

40-
## TODO Uncomment when we incorporate Graphviz DOT files into documentation
4166
# ##
4267
# ## SVG files (from Graphviz dot files)
4368
# ##
44-
# set(DOT_FILES
45-
# globalcontext-processes
46-
# globalcontext-atoms
47-
# globalcontext-modules
48-
# )
49-
# find_package(Graphviz)
50-
# if(GRAPHVIZ_FOUND)
51-
# message("Graphiz found")
52-
# file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/svg)
53-
# foreach(DOT_FILE ${DOT_FILES})
54-
# add_custom_command(
55-
# OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/svg/${DOT_FILE}.svg
56-
# COMMAND dot -Tsvg ${CMAKE_CURRENT_SOURCE_DIR}/graphviz/${DOT_FILE}.dot > ${CMAKE_CURRENT_BINARY_DIR}/html/svg/${DOT_FILE}.svg
57-
# DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/graphviz/${DOT_FILE}.dot
58-
# WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
59-
# COMMENT "Generating SVG for ${DOT_FILE}.dot"
60-
# VERBATIM
61-
# )
62-
# set(ERLANG_DOTFILE_TARGETS ${ERLANG_DOTFILE_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/html/svg/${DOT_FILE}.svg)
63-
# endforeach()
64-
# else()
65-
# message("WARNING: Graphviz not found. Some images may be missing in generated documentation.")
66-
# endif()
67-
68-
##
69-
## Doxygen (C) API documentation
70-
##
71-
find_package(Doxygen)
72-
if(DOXYGEN_FOUND)
73-
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
74-
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/atomvmlib)
75-
add_custom_target(doxygen-html # ALL
76-
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
77-
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
78-
COMMENT "Generating documentation" VERBATIM
79-
DEPENDS ${ERLANG_EDOC_TARGETS} ${ERLANG_DOTFILE_TARGETS}
80-
)
69+
set(DOT_FILES
70+
globalcontext-processes
71+
globalcontext-atoms
72+
globalcontext-modules
73+
)
74+
find_package(Graphviz)
75+
if(GRAPHVIZ_FOUND)
76+
message("Graphiz found")
77+
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/src/_static)
78+
foreach(DOT_FILE ${DOT_FILES})
79+
add_custom_command(
80+
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg
81+
COMMAND dot -Tsvg ${CMAKE_CURRENT_SOURCE_DIR}/graphviz/${DOT_FILE}.dot > ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg
82+
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/graphviz/${DOT_FILE}.dot
83+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
84+
COMMENT "Generating SVG for ${DOT_FILE}.dot" VERBATIM
85+
)
86+
set(ERLANG_DOTFILE_TARGETS ${ERLANG_DOTFILE_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg)
87+
endforeach()
8188
else()
82-
message("Unable to find doxygen -- no documentation will be generated")
89+
message("WARNING: Graphviz not found. Some images may be missing in generated documentation.")
8390
endif()
8491

8592
##
@@ -92,31 +99,86 @@ if(SPHINX_FOUND)
9299

93100
message("Sphinx found: ${SPHINX_BUILD_EXECUTABLE}")
94101
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
102+
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
103+
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/libatomvm)
95104
add_custom_target(sphinx-html
96-
${SPHINX_BUILD_EXECUTABLE} -b html -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/src ${CMAKE_CURRENT_BINARY_DIR}/html
105+
${SPHINX_BUILD_EXECUTABLE} -b html -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/html/
97106
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
98107
COMMENT "Generating Sphinx HTML documentation" VERBATIM
99-
DEPENDS ${ERLANG_DOTFILE_TARGETS}
108+
DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS}
100109
)
101110

102111
add_custom_target(sphinx-pdf
103-
${SPHINX_BUILD_EXECUTABLE} -b rinoh -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/src ${CMAKE_CURRENT_BINARY_DIR}/html/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/
104113
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
105114
COMMENT "Generating Sphinx PDF documentation" VERBATIM
106-
DEPENDS ${ERLANG_DOTFILE_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py
115+
DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py
107116
)
108117

109118
add_custom_target(sphinx-epub
110-
${SPHINX_BUILD_EXECUTABLE} -b epub -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/src ${CMAKE_CURRENT_BINARY_DIR}/html/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/
111120
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
112121
COMMENT "Generating Sphinx PDF documentation" VERBATIM
113-
DEPENDS ${ERLANG_DOTFILE_TARGETS}
122+
DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py
114123
)
124+
125+
## This target is intended for CI `Publish Docs` workflow.
126+
if ($ENV{CI})
127+
add_custom_target(GitHub_CI_Publish_Docs
128+
COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_BINARY_DIR}/html /home/runner/work/AtomVM/AtomVM/www/doc/${BRANCH_NAME}
129+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
130+
COMMENT "Copying html docs to publish location /home/runner/work/AtomVM/AtomVM/www/doc/${BRANCH_NAME}." VERBATIM
131+
DEPENDS doc /home/runner/work/AtomVM/AtomVM/www/doc $ENV{BRANCH_NAME}
132+
)
133+
endif()
134+
115135
else()
116136
message("Unable to find Sphinx -- no Sphinx documentation will be generated")
117137
endif()
118138

139+
## Fix URLs and change title to include "library" instead of "application"
140+
foreach(LIBAVM_ERL_LIB estdlib eavmlib alisp etest)
141+
add_custom_command(TARGET edoc-${LIBAVM_ERL_LIB}
142+
POST_BUILD
143+
COMMAND sed -i -e "s/\.md/\.html/g" -e "s/application/library/g" ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/erlang/${LIBAVM_ERL_LIB}/README.md
144+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
145+
COMMENT "Fixing html link locations for ${LIBAVM_ERL_LIB}." VERBATIM
146+
)
147+
endforeach(LIBAVM_ERL_LIB)
119148

120149
add_custom_target(doc #ALL
121-
DEPENDS ${ERLANG_EDOC_TARGETS} doxygen-html sphinx-html sphinx-pdf sphinx-epub
150+
DEPENDS ${ERLANG_EDOC_TARGETS} sphinx-html sphinx-pdf sphinx-epub
122151
)
152+
153+
if (TARGET GitHub_CI_Publish_Docs)
154+
155+
add_custom_command(
156+
COMMAND mkdir -p /home/runner/work/AtomVM/AtomVM/www/doc
157+
OUTPUT /home/runner/work/AtomVM/AtomVM/www/doc
158+
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
159+
COMMENT "Prepare publish directory structure." VERBATIM
160+
)
161+
162+
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/pdf)
163+
add_custom_command(TARGET sphinx-pdf POST_BUILD
164+
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/pdf/AtomVM-${BRANCH_NAME}.pdf ${CMAKE_CURRENT_BINARY_DIR}/html/pdf/
165+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/pdf
166+
COMMENT "Copying pdf to download location" VERBATIM
167+
DEPENDS $ENV{BRANCH_NAME}
168+
)
169+
170+
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/epub)
171+
add_custom_command(TARGET sphinx-epub POST_BUILD
172+
COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/epub/AtomVM-${BRANCH_NAME}.epub" "${CMAKE_CURRENT_BINARY_DIR}/html/epub/"
173+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/epub
174+
COMMENT "Copying epub to download location." VERBATIM
175+
DEPENDS $ENV{BRANCH_NAME}
176+
)
177+
178+
add_custom_command(TARGET sphinx-html POST_BUILD
179+
COMMAND touch .nojekyll
180+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
181+
COMMENT "Creating .nojekyll to allow style content on GitHub Pages." VERBATIM
182+
)
183+
184+
endif()

0 commit comments

Comments
 (0)