Skip to content

Commit 0c0e775

Browse files
jeremyfajeremyfa
committed
Start using a different method to generate docs (wip)
1 parent aa73a64 commit 0c0e775

12 files changed

Lines changed: 2076 additions & 286 deletions

File tree

.github/workflows/deploy-api-docs.yml renamed to .github/workflows/build-api-docs.yml

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,10 @@ on:
33
push:
44
branches:
55
- main
6-
repository_dispatch:
7-
types: [deploy-api-docs]
86

97
jobs:
108

11-
deploy-api-docs:
9+
build-api-docs:
1210
runs-on: ubuntu-22.04-arm
1311
steps:
1412
- uses: actions/checkout@v2
@@ -59,17 +57,12 @@ jobs:
5957
working-directory: ceramic/tools
6058
run: |
6159
./ceramic link
62-
- name: Generate API Docs
60+
- name: Install haxelibs
6361
working-directory: .
6462
run: |
65-
./gen-docs.sh
66-
- name: Add .nojekyll
63+
mkdir .haxelib
64+
haxelib install hxnodejs
65+
- name: Generate API Docs
6766
working-directory: .
6867
run: |
69-
touch docs/.nojekyll
70-
- name: Deploy to Github Pages
71-
uses: ceramic-engine/actions-gh-pages@v1.1.0
72-
env:
73-
PUBLISH_DIR: docs
74-
PUBLISH_BRANCH: gh-pages
75-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
68+
./gen-docs.sh

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,8 @@
77
/node_modules
88
/project
99
/ceramic.zip
10-
/ceramic
10+
/ceramic
11+
/docs-md
12+
/docs-xml
13+
/gen-docs/bin
14+
/gen-docs/temp.json

‎ceramic.yml‎

Lines changed: 13 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -20,54 +20,19 @@ app:
2020
+defines:
2121
- ceramic_unity_default_net_std
2222

23-
if use_arcade:
24-
+plugins:
25-
- arcade
26-
27-
if use_nape:
28-
+plugins:
29-
- nape
30-
31-
if use_script:
32-
+plugins:
33-
- script
34-
35-
if use_spine:
36-
+plugins:
37-
- spine
38-
39-
if use_sprite:
40-
+plugins:
41-
- sprite
42-
43-
if use_tilemap:
44-
+plugins:
45-
- tilemap
46-
47-
if use_ui:
48-
+plugins:
49-
- ui
50-
51-
if use_arcade:
52-
+plugins:
53-
- arcade
54-
55-
if use_dialogs:
56-
+plugins:
57-
- dialogs
58-
59-
if use_elements:
60-
+plugins:
61-
- ui
62-
- elements
63-
64-
if use_gif:
65-
+plugins:
66-
- gif
67-
68-
if use_imgui:
69-
+plugins:
70-
- imgui
23+
plugins:
24+
- arcade
25+
- nape
26+
- script
27+
- spine
28+
- sprite
29+
- ase
30+
- tilemap
31+
- ldtk
32+
- ui
33+
- dialogs
34+
- elements
35+
- gif
7136

7237
if web:
7338
+defines:

‎gen-docs.sh‎

Lines changed: 31 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -4,63 +4,12 @@ set -e
44
cd ${0%/*}
55

66
rm -rf ./docs
7+
rm -rf ./docs-xml
78

89
ceramic clay setup web
910
ceramic clay hxml web > docs.hxml
1011
$(ceramic haxe) docs.hxml --xml ../../../docs/clay-web.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
1112

12-
ceramic clay setup web --variant use_tilemap
13-
ceramic clay hxml web --variant use_tilemap > docs.hxml
14-
$(ceramic haxe) docs.hxml --xml ../../../docs/tilemap-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
15-
16-
ceramic clay setup web --variant use_ase
17-
ceramic clay hxml web --variant use_ase > docs.hxml
18-
$(ceramic haxe) docs.hxml --xml ../../../docs/ase-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
19-
20-
ceramic clay setup web --variant use_ldtk
21-
ceramic clay hxml web --variant use_ldtk > docs.hxml
22-
$(ceramic haxe) docs.hxml --xml ../../../docs/ldtk-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
23-
24-
ceramic clay setup web --variant use_ui
25-
ceramic clay hxml web --variant use_ui > docs.hxml
26-
$(ceramic haxe) docs.hxml --xml ../../../docs/ui-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
27-
28-
ceramic clay setup web --variant use_sprite
29-
ceramic clay hxml web --variant use_sprite > docs.hxml
30-
$(ceramic haxe) docs.hxml --xml ../../../docs/sprite-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
31-
32-
ceramic clay setup web --variant use_spine
33-
ceramic clay hxml web --variant use_spine > docs.hxml
34-
$(ceramic haxe) docs.hxml --xml ../../../docs/spine-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
35-
36-
ceramic clay setup web --variant use_arcade
37-
ceramic clay hxml web --variant use_arcade > docs.hxml
38-
$(ceramic haxe) docs.hxml --xml ../../../docs/arcade-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
39-
40-
ceramic clay setup web --variant use_nape
41-
ceramic clay hxml web --variant use_nape > docs.hxml
42-
$(ceramic haxe) docs.hxml --xml ../../../docs/nape-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
43-
44-
ceramic clay setup web --variant use_imgui
45-
ceramic clay hxml web --variant use_imgui > docs.hxml
46-
$(ceramic haxe) docs.hxml --xml ../../../docs/imgui-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
47-
48-
ceramic clay setup web --variant use_dialogs
49-
ceramic clay hxml web --variant use_dialogs > docs.hxml
50-
$(ceramic haxe) docs.hxml --xml ../../../docs/dialogs-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
51-
52-
ceramic clay setup web --variant use_gif
53-
ceramic clay hxml web --variant use_gif > docs.hxml
54-
$(ceramic haxe) docs.hxml --xml ../../../docs/gif-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
55-
56-
ceramic clay setup web --variant use_elements
57-
ceramic clay hxml web --variant use_elements > docs.hxml
58-
$(ceramic haxe) docs.hxml --xml ../../../docs/elements-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
59-
60-
ceramic clay setup web --variant use_script
61-
ceramic clay hxml web --variant use_script > docs.hxml
62-
$(ceramic haxe) docs.hxml --xml ../../../docs/script-plugin.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
63-
6413
if [ "$(uname)" == "Darwin" ]; then
6514
ceramic clay setup mac
6615
ceramic clay hxml mac > docs.hxml
@@ -73,12 +22,36 @@ fi
7322

7423
ceramic headless setup node
7524
ceramic headless hxml node > docs.hxml
76-
$(ceramic haxe) docs.hxml --xml ../../../docs/headless.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
25+
$(ceramic haxe) docs.hxml --xml ../../../docs/headless.xml -D doc-gen -D documentation -D no_backend_docs -D dox_events --no-output -D no-compilation
7726

7827
ceramic unity setup unity
7928
ceramic unity hxml unity > docs.hxml
80-
$(ceramic haxe) docs.hxml --xml ../../../docs/unity.xml -D doc-gen -D documentation -D dox_events --no-output -D no-compilation
81-
82-
$(ceramic haxelib) run dox -i ./docs --output-path docs --keep-field-order --exclude 'zpp_nape|microsoft|unityengine|fuzzaldrin|gif|timestamp|stb|sys|spec|sdl|polyline|poly2tri|opengl|openal|ogg|js|hsluv|hscript|glew|format|earcut|cs|cpp|com|assets|ceramic.scriptable|ceramic.macros' --title 'Ceramic API'
83-
84-
node transform-docs.js
29+
$(ceramic haxe) docs.hxml --xml ../../../docs/unity.xml -D doc-gen -D documentation -D no_backend_docs -D dox_events --no-output -D no-compilation
30+
31+
mkdir docs-xml
32+
cp -f docs/*.xml docs-xml
33+
34+
# Build gen-docs tool
35+
cd gen-docs
36+
haxe build.hxml
37+
cd ..
38+
39+
# Generate markdown documentation from XML files
40+
rm -rf ./docs-md
41+
mkdir -p docs-md
42+
43+
# Generate markdown for each XML file
44+
for xml_file in docs-xml/*.xml; do
45+
base_name=$(basename "$xml_file" .xml)
46+
echo "Generating markdown for $base_name..."
47+
node gen-docs/bin/gen-docs.js markdown "$xml_file" "docs-md/$base_name"
48+
49+
# Generate table of contents
50+
echo "Generating table of contents for $base_name..."
51+
node gen-docs/bin/gen-docs.js toc "$xml_file" "docs-md/$base_name/toc.json"
52+
done
53+
54+
# Old dox command (commented out since we're using our own generator now)
55+
# $(ceramic haxelib) run dox -i ./docs --output-path docs --keep-field-order --exclude 'zpp_nape|microsoft|unityengine|fuzzaldrin|gif|timestamp|stb|sys|spec|sdl|polyline|poly2tri|opengl|openal|ogg|js|hsluv|hscript|glew|format|earcut|cs|cpp|com|assets|ceramic.scriptable|ceramic.macros' --title 'Ceramic API'
56+
57+
# node transform-docs.js

‎gen-docs/build.hxml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
-cp src
2+
-main Main
3+
-lib hxnodejs
4+
-js bin/gen-docs.js

‎gen-docs/src/ApiTypes.hx‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
typedef ApiData = {
2+
var types:Array<ApiType>;
3+
var inheritanceMap:Map<String, Array<String>>; // Maps a type to all types that extend/implement it
4+
}
5+
6+
typedef ApiType = {
7+
var kind:TypeKind;
8+
var path:String;
9+
var module:Null<String>;
10+
var file:String;
11+
var params:String;
12+
var doc:Null<String>;
13+
var meta:Array<MetaData>;
14+
var isPrivate:Bool;
15+
var isExtern:Bool;
16+
var isFinal:Bool;
17+
var isInterface:Bool;
18+
var ?impl:Null<String>; // For abstracts
19+
var ?superClass:Null<TypePath>; // For classes
20+
var ?interfaces:Array<TypePath>; // For classes
21+
var ?from:Array<TypePath>; // For abstracts
22+
var ?to:Array<TypePath>; // For abstracts
23+
var ?underlying:Null<TypePath>; // For abstracts and typedefs
24+
var ?constructors:Array<EnumConstructor>; // For enums
25+
var ?fields:Array<Field>; // For classes, abstracts, interfaces
26+
}
27+
28+
enum TypeKind {
29+
TClass;
30+
TInterface;
31+
TEnum;
32+
TTypedef;
33+
TAbstract;
34+
}
35+
36+
typedef TypePath = {
37+
var path:String;
38+
var params:Array<TypePath>;
39+
}
40+
41+
typedef MetaData = {
42+
var name:String;
43+
var params:Null<Array<String>>;
44+
}
45+
46+
typedef EnumConstructor = {
47+
var name:String;
48+
var args:Null<Array<FunctionArg>>;
49+
var doc:Null<String>;
50+
var meta:Array<MetaData>;
51+
}
52+
53+
typedef Field = {
54+
var name:String;
55+
var type:FieldType;
56+
var isPublic:Bool;
57+
var isStatic:Bool;
58+
var line:Null<Int>;
59+
var getter:Null<String>;
60+
var setter:Null<String>;
61+
var expr:Null<String>;
62+
var doc:Null<String>;
63+
var meta:Array<MetaData>;
64+
var overloads:Null<Array<Field>>;
65+
}
66+
67+
typedef FieldType = {
68+
var kind:FieldTypeKind;
69+
var args:Null<Array<FunctionArg>>; // For functions
70+
var ret:Null<TypePath>; // For functions
71+
var type:Null<TypePath>; // For variables
72+
}
73+
74+
enum FieldTypeKind {
75+
FVar;
76+
FMethod;
77+
}
78+
79+
typedef FunctionArg = {
80+
var name:String;
81+
var type:TypePath;
82+
var opt:Bool;
83+
var value:Null<String>;
84+
}

0 commit comments

Comments
 (0)