Skip to content

Commit b2571ce

Browse files
ReenigneArcherReenigneArcher
authored
docs: add jsdoc and rtd build (#101)
1 parent 36dab7e commit b2571ce

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+879
-54
lines changed

‎.flake8

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[flake8]
2+
filename =
3+
*.py
4+
max-line-length = 120
5+
extend-exclude =
6+
venv/

‎.github/workflows/ci.yml

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,26 @@ jobs:
9494
token: ${{ secrets.CODECOV_TOKEN }}
9595
verbose: true
9696

97+
release:
98+
if: ${{ needs.setup_release.outputs.publish_release == 'true' }}
99+
needs:
100+
- setup_release
101+
- build
102+
runs-on: ubuntu-latest
103+
steps:
104+
- name: Create Release
105+
id: action
106+
uses: LizardByte/[email protected]
107+
with:
108+
allowUpdates: false
109+
artifacts: ''
110+
body: ${{ needs.setup_release.outputs.release_body }}
111+
generateReleaseNotes: ${{ needs.setup_release.outputs.release_generate_release_notes }}
112+
name: ${{ needs.setup_release.outputs.release_tag }}
113+
prerelease: true
114+
tag: ${{ needs.setup_release.outputs.release_tag }}
115+
token: ${{ secrets.GH_BOT_TOKEN }}
116+
97117
publish-gpr:
98118
if: ${{ needs.setup_release.outputs.publish_release == 'true' }}
99119
needs:

‎.github/workflows/update-docs.yml

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
# This action is centrally managed in https://github.com/<organization>/.github/
3+
# Don't make changes to this file in this repo as they will be overwritten with changes made to the same file in
4+
# the above-mentioned repo.
5+
6+
# Use the `rtd` repository label to identify repositories that should trigger have this workflow.
7+
# If the project slug is not the repository name, add a repository variable named `READTHEDOCS_SLUG` with the value of
8+
# the ReadTheDocs project slug.
9+
10+
# Update readthedocs on release events.
11+
12+
name: Update docs
13+
14+
on:
15+
release:
16+
types: [created, edited, deleted]
17+
18+
concurrency:
19+
group: "${{ github.workflow }}-${{ github.event.release.tag_name }}"
20+
cancel-in-progress: true
21+
22+
jobs:
23+
update-docs:
24+
env:
25+
RTD_SLUG: ${{ vars.READTHEDOCS_SLUG }}
26+
RTD_TOKEN: ${{ secrets.READTHEDOCS_TOKEN }}
27+
TAG: ${{ github.event.release.tag_name }}
28+
if: >-
29+
!github.event.release.draft
30+
runs-on: ubuntu-latest
31+
steps:
32+
- name: Get RTD_SLUG
33+
run: |
34+
# if the RTD_SLUG is not set, use the repository name in lowercase
35+
if [ -z "${RTD_SLUG}" ]; then
36+
RTD_SLUG=$(echo "${{ github.event.repository.name }}" | tr '[:upper:]' '[:lower:]')
37+
fi
38+
echo "RTD_SLUG=${RTD_SLUG}" >> $GITHUB_ENV
39+
40+
- name: Deactivate deleted release
41+
if: >-
42+
github.event_name == 'release' &&
43+
github.event.action == 'deleted'
44+
run: |
45+
json_body=$(jq -n \
46+
--arg active "false" \
47+
--arg hidden "false" \
48+
--arg privacy_level "public" \
49+
'{active: $active, hidden: $hidden, privacy_level: $privacy_level}')
50+
51+
curl \
52+
-X PATCH \
53+
-H "Authorization: Token ${RTD_TOKEN}" \
54+
https://readthedocs.org/api/v3/projects/${RTD_SLUG}/versions/${TAG}/ \
55+
-H "Content-Type: application/json" \
56+
-d "$json_body"
57+
58+
- name: Check if edited release is latest GitHub release
59+
id: check
60+
if: >-
61+
github.event_name == 'release' &&
62+
github.event.action == 'edited'
63+
uses: actions/github-script@v7
64+
with:
65+
script: |
66+
const latestRelease = await github.rest.repos.getLatestRelease({
67+
owner: context.repo.owner,
68+
repo: context.repo.repo
69+
});
70+
71+
core.setOutput('isLatestRelease', latestRelease.data.tag_name === context.payload.release.tag_name);
72+
73+
- name: Update RTD project
74+
# changing the default branch in readthedocs makes "latest" point to that branch/tag
75+
# we can also update other properties like description, etc.
76+
if: >-
77+
steps.check.outputs.isLatestRelease == 'true'
78+
run: |
79+
json_body=$(jq -n \
80+
--arg default_branch "${TAG}" \
81+
--arg description "${{ github.event.repository.description }}" \
82+
'{default_branch: $default_branch}')
83+
84+
# change the default branch to the latest release
85+
curl \
86+
-X PATCH \
87+
-H "Authorization: Token ${RTD_TOKEN}" \
88+
-H "Content-Type: application/json" \
89+
https://readthedocs.org/api/v3/projects/${RTD_SLUG}/ \
90+
-d "$json_body"
91+
92+
# trigger a build for the latest version
93+
curl \
94+
-X POST \
95+
-H "Authorization: Token ${RTD_TOKEN}" \
96+
https://readthedocs.org/api/v3/projects/${RTD_SLUG}/versions/latest/builds/

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,7 @@ junit.xml
1010
coverage/
1111

1212
# Ignore build artifacts
13+
_readthedocs/
14+
build/
1315
dist/
1416
lizardbyte-shared-web*.tgz

‎.readthedocs.yaml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
version: 2
3+
build:
4+
os: "ubuntu-24.04"
5+
tools:
6+
nodejs: "22"
7+
python: "3.13"
8+
ruby: "3.3"
9+
commands:
10+
- 'echo "output directory: ${READTHEDOCS_OUTPUT}html"'
11+
# shared-web build
12+
- npm install
13+
- npm run build
14+
- npm pack
15+
- mkdir -p ${READTHEDOCS_OUTPUT}html/dist
16+
- cp -r dist/* ${READTHEDOCS_OUTPUT}html/dist
17+
# jsdoc build
18+
- npm run generate-docs
19+
# jekyll example build
20+
- 'echo "baseurl: projects/shared-web/$READTHEDOCS_VERSION"/jekyll >> ./examples/jekyll/_config.yml'
21+
- cd examples/jekyll && npm install
22+
- cd examples/jekyll && npm run build
23+
# doxygen example build
24+
- cd examples/doxygen && npm install
25+
- cd examples/doxygen && npm run build
26+
# sphinx example build
27+
- cd examples/sphinx && npm install
28+
- cd examples/sphinx && npm run build
29+
- cd examples/sphinx && npm run lint
30+
# debug output
31+
- cd ${READTHEDOCS_OUTPUT}html && ls -la -R

‎docs/static/avatar.png

11.3 KB
Loading

‎docs/static/favicon.ico

112 KB
Binary file not shown.

‎docs/static/logo.png

23.9 KB
Loading

‎examples/doxygen/Doxyfile

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
DOXYFILE_ENCODING = UTF-8
2+
3+
# project metadata
4+
DOCSET_BUNDLE_ID = dev.lizardbyte.shared-web.doxygen
5+
DOCSET_PUBLISHER_ID = dev.lizardbyte.shared-web.doxygen
6+
DOCSET_PUBLISHER_NAME = LizardByte
7+
PROJECT_BRIEF = "Example use of @lizardbyte/shared-web in doxygen html."
8+
PROJECT_ICON = $(READTHEDOCS_OUTPUT)html/favicon.ico
9+
PROJECT_LOGO = $(READTHEDOCS_OUTPUT)html/logo.png
10+
PROJECT_NAME = shared-web Doxygen sample
11+
12+
# doxygen-awesome-css
13+
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
14+
HTML_COLORSTYLE_HUE = 209
15+
HTML_COLORSTYLE_SAT = 255
16+
HTML_COLORSTYLE_GAMMA = 113
17+
HTML_COPY_CLIPBOARD = NO # required for Doxygen >= 1.10.0
18+
HTML_EXTRA_FILES = ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
19+
HTML_EXTRA_FILES += ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
20+
HTML_EXTRA_FILES += ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
21+
HTML_EXTRA_FILES += ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
22+
HTML_EXTRA_FILES += ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-tabs.js
23+
HTML_EXTRA_STYLESHEET = ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome.css
24+
HTML_HEADER = header.html
25+
26+
# @lizardbyte/shared-web
27+
HTML_EXTRA_FILES += ./node_modules/@lizardbyte/shared-web/dist/crowdin.js
28+
HTML_EXTRA_STYLESHEET += ./node_modules/@lizardbyte/shared-web/dist/crowdin-doxygen-css.css
29+
30+
# general settings
31+
CASE_SENSE_NAMES = YES
32+
CREATE_SUBDIRS = NO
33+
DISABLE_INDEX = NO
34+
FULL_SIDEBAR = NO
35+
GENERATE_HTML = YES
36+
GENERATE_LATEX = NO
37+
GENERATE_TREEVIEW = YES
38+
GENERATE_XML = NO
39+
HAVE_DOT = NO
40+
HTML_OUTPUT = html
41+
MARKDOWN_ID_STYLE = GITHUB
42+
MARKDOWN_SUPPORT = YES
43+
PROJECT_NUMBER = $(READTHEDOCS_VERSION)
44+
OUTPUT_DIRECTORY = $(READTHEDOCS_OUTPUT)html/doxygen
45+
RECURSIVE = YES
46+
WARN_AS_ERROR = FAIL_ON_WARNINGS
47+
WARN_IF_DOC_ERROR = YES
48+
WARN_IF_INCOMPLETE_DOC = YES
49+
WARN_IF_UNDOC_ENUM_VAL = YES
50+
WARN_IF_UNDOCUMENTED = YES
51+
WARN_NO_PARAMDOC = YES
52+
WARNINGS = YES
53+
54+
USE_MDFILE_AS_MAINPAGE = sample.md
55+
INPUT = sample.md

‎examples/doxygen/header.html

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<!-- HTML header for doxygen 1.10.0-->
2+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3+
<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
4+
<head>
5+
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
6+
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
7+
<meta name="generator" content="Doxygen $doxygenversion"/>
8+
<meta name="viewport" content="width=device-width, initial-scale=1"/>
9+
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
10+
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
11+
<link rel="icon" href="$relpath^$projecticon" type="image/x-icon" />
12+
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
13+
<!--BEGIN DISABLE_INDEX-->
14+
<!--BEGIN FULL_SIDEBAR-->
15+
<script type="text/javascript">var page_layout=1;</script>
16+
<!--END FULL_SIDEBAR-->
17+
<!--END DISABLE_INDEX-->
18+
<script type="text/javascript" src="$relpath^jquery.js"></script>
19+
<script type="text/javascript" src="$relpath^dynsections.js"></script>
20+
$treeview
21+
$search
22+
$mathjax
23+
$darkmode
24+
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
25+
$extrastylesheet
26+
27+
<!--LIZARDBYTE/SHARED-WEB START-->
28+
<script type="text/javascript" src="$relpath^crowdin.js"></script>
29+
<script type="text/javascript">
30+
initCrowdIn('LizardByte-docs', null);
31+
</script>
32+
33+
<!--DOXYGEN-AWESOME START-->
34+
<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
35+
<script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
36+
<script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
37+
<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
38+
<script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
39+
<script type="text/javascript">
40+
DoxygenAwesomeDarkModeToggle.init()
41+
DoxygenAwesomeFragmentCopyButton.init()
42+
DoxygenAwesomeParagraphLink.init()
43+
DoxygenAwesomeInteractiveToc.init()
44+
DoxygenAwesomeTabs.init()
45+
</script>
46+
<!--DOXYGEN-AWESOME END-->
47+
</head>
48+
<body>
49+
<!--BEGIN DISABLE_INDEX-->
50+
<!--BEGIN FULL_SIDEBAR-->
51+
<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
52+
<!--END FULL_SIDEBAR-->
53+
<!--END DISABLE_INDEX-->
54+
55+
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
56+
57+
<!--BEGIN TITLEAREA-->
58+
<div id="titlearea">
59+
<table cellspacing="0" cellpadding="0">
60+
<tbody>
61+
<tr id="projectrow">
62+
<!--BEGIN PROJECT_LOGO-->
63+
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
64+
<!--END PROJECT_LOGO-->
65+
<!--BEGIN PROJECT_NAME-->
66+
<td id="projectalign">
67+
<div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
68+
</div>
69+
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
70+
</td>
71+
<!--END PROJECT_NAME-->
72+
<!--BEGIN !PROJECT_NAME-->
73+
<!--BEGIN PROJECT_BRIEF-->
74+
<td>
75+
<div id="projectbrief">$projectbrief</div>
76+
</td>
77+
<!--END PROJECT_BRIEF-->
78+
<!--END !PROJECT_NAME-->
79+
<!--BEGIN DISABLE_INDEX-->
80+
<!--BEGIN SEARCHENGINE-->
81+
<!--BEGIN !FULL_SIDEBAR-->
82+
<td>$searchbox</td>
83+
<!--END !FULL_SIDEBAR-->
84+
<!--END SEARCHENGINE-->
85+
<!--END DISABLE_INDEX-->
86+
</tr>
87+
<!--BEGIN SEARCHENGINE-->
88+
<!--BEGIN FULL_SIDEBAR-->
89+
<tr><td colspan="2">$searchbox</td></tr>
90+
<!--END FULL_SIDEBAR-->
91+
<!--END SEARCHENGINE-->
92+
</tbody>
93+
</table>
94+
</div>
95+
<!--END TITLEAREA-->
96+
<!-- end header part -->

0 commit comments

Comments
 (0)