Documentation Improvements

.github/workflows/build-doc.yml

@@ -81,16 +81,17 @@ jobs:
       - name: Generate markdown
         shell: msys2 {0}
         run: |
-          ./shards.exe src/tests/infos-docs.edn
-          mv docs/docs/docs/shards/General/UI.md docs/docs/docs/shards/UI/index.md
+          ./shards.exe docs/generate.edn
       - name: Upload markdown
         uses: actions/upload-artifact@v3
         with:
           name: docs-markdown
           path: |
-            docs/docs/docs/shards/**/*.md
-            !docs/docs/docs/shards/index.md
-            !docs/docs/docs/shards/types.md
+            docs/docs/reference/shards/**/*.md
+            docs/docs/reference/enums/**/*.md
+            !docs/docs/reference/enums/index.md
+            !docs/docs/reference/shards/index.md
+            !docs/docs/reference/shards/types.md
           if-no-files-found: error
 
   #
@@ -124,7 +125,7 @@ jobs:
         uses: actions/download-artifact@v3
         with:
           name: docs-markdown
-          path: shards/docs/docs/docs/shards
+          path: shards/docs/docs/reference
       - name: Download samples logs
         uses: actions/download-artifact@v3
         with:

.github/workflows/build-linux.yml

@@ -128,20 +128,21 @@ jobs:
           ./shards ../src/tests/edn.edn
           ./shards ../src/tests/pure.edn
           ./shards ../src/tests/shell.clj
+          ./shards ../src/tests/infos.clj
       - name: Test (Debug)
         # Test that only works in Debug build go there
         if: ${{ steps.setup.outputs.build-type == 'Debug' }}
         env:
           RUST_BACKTRACE: 1
         run: |
           cd build
-          ./shards ../src/tests/shards.clj
+          ./shards ../src/tests/export-strings.edn
       - name: Test doc samples (non-UI)
         env:
           RUST_BACKTRACE: 1
         run: |
           cd docs/samples
-          for i in $(find shards -name '*.edn' ! -path '*UI*');
+          for i in $(find shards -name '*.edn' \( ! -path '*UI*' ! -path '*GFX*' \));
           do
             echo "Running sample $i";
             ../../build/shards run-sample.edn --file "$i";

.github/workflows/build-macos.yml

@@ -161,7 +161,7 @@ jobs:
           RUST_BACKTRACE: 1
         run: |
           cd docs/samples
-          for i in $(find shards -name '*.edn' ! -path '*UI*');
+          for i in $(find shards -name '*.edn' \( ! -path '*UI*' ! -path '*GFX*' \));
           do
             echo "Running sample $i";
             ../../build/shards run-sample.edn --file "$i";

.github/workflows/build-windows.yml

@@ -177,7 +177,9 @@ jobs:
           ./bootstrap
           mkdir build
           cd build
-          cmake -G Ninja -DCMAKE_BUILD_TYPE=${{ steps.setup.outputs.build-type }} -DUSE_LIBBACKTRACE=${{ steps.setup.outputs.bitness == '64bits' }} ..
+          # Some commits hang the linking step during one of the following targets
+          # Passing -DUSE_LLD=OFF will use the default mingw ld linker which doesn't have this issue
+          cmake -G Ninja -DUSE_LLD=OFF -DCMAKE_BUILD_TYPE=${{ steps.setup.outputs.build-type }} -DUSE_LIBBACKTRACE=${{ steps.setup.outputs.bitness == '64bits' }} ..
           ninja ${{ steps.setup.outputs.build-target }}
       - name: Test runtime (Debug)
         if: ${{ steps.setup.outputs.runtime-tests == 'true' && steps.setup.outputs.build-type == 'Debug' }}
@@ -323,12 +325,12 @@ jobs:
         shell: msys2 {0}
         run: |
           cd docs/samples
-          for i in $(find shards -name '*.edn' ! -path '*UI*');
+          for i in $(find shards -name '*.edn' \( ! -path '*UI*' ! -path '*GFX*' \));
           do
             echo "Running sample $i";
             ../../build/shards.exe run-sample.edn --file "$i";
           done
-      - name: Test doc samples (UI)
+      - name: Test doc samples (GFX)
         # NOTE: Graphics backend doesn't run on 32bits
         if: ${{ steps.setup.outputs.bitness == '64bits' }}
         env:
@@ -337,7 +339,7 @@ jobs:
         shell: msys2 {0}
         run: |
           cd docs/samples
-          for i in $(find shards -name '*.edn' -path '*UI*');
+          for i in $(find shards -name '*.edn' \( -path '*UI*' -or -path '*GFX*' \));
           do
             echo "Running sample $i";
             ../../build/shards.exe run-sample.edn --file "$i";

.github/workflows/test-linux-gpu.yml

@@ -101,7 +101,7 @@ jobs:
 
           echo "Running onnx test"
           build/shards src/tests/onnx.edn
-      - name: Test doc samples (UI)
+      - name: Test doc samples (GFX)
         env:
           RUST_BACKTRACE: 1
         run: |
@@ -110,7 +110,7 @@ jobs:
           Xvfb "$DISPLAY" &
 
           cd docs/samples
-          for i in $(find shards -name '*.edn' -path '*UI*');
+          for i in $(find shards -name '*.edn' \( -path '*UI*' -or -path '*GFX*'\));
           do
             echo "Running sample $i";
             ../../build/shards run-sample.edn --file "$i";

.gitignore

@@ -60,4 +60,4 @@ src/tests/example-dwt.wav
 src/tests/example.wav.png
 src/tests/svgtest.png
 src/tests/mobilenetv2-7.onnx
-/docs/docs/docs/shards/**/*.md
+/docs/docs/reference/shards/**/*.md

cmake/Platform.cmake

@@ -38,6 +38,11 @@ if(USE_FPIC)
   list(APPEND EXTERNAL_CMAKE_ARGS -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DSDL_STATIC_PIC=ON)
 endif()
 
+# Force ninja to use response files on windows when command line might be too long otherwise
+if(CMAKE_HOST_WIN32)
+  SET(CMAKE_NINJA_FORCE_RESPONSE_FILE ON CACHE INTERNAL "" FORCE)
+endif()
+
 if(EMSCRIPTEN)
   if(CMAKE_BUILD_TYPE STREQUAL "RelWithDebInfo")
     add_compile_options(-g1 -Os)
@@ -117,7 +122,11 @@ if(NOT MSVC)
   add_compile_options(-ffast-math -fno-finite-math-only -funroll-loops -Wno-multichar)
 endif()
 
-if((WIN32 AND CMAKE_BUILD_TYPE STREQUAL "Debug") OR FORCE_USE_LLD)
+if(WIN32 AND (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") AND (CMAKE_BUILD_TYPE STREQUAL "Debug"))
+  set(USE_LLD_DEFAULT ON)
+endif()
+option(USE_LLD "Override linker tools to use lld & llvm-ar/ranlib" ${USE_LLD_DEFAULT})
+if(USE_LLD)
   add_link_options(-fuse-ld=lld)
   SET(CMAKE_AR llvm-ar)
   SET(CMAKE_RANLIB llvm-ranlib)

cmake/Rust.cmake

@@ -61,10 +61,12 @@ else()
 endif()
 message(STATUS "RUST_BUILD_SUBDIR = ${RUST_BUILD_SUBDIR}")
 
-set(RUST_FLAGS ${RUST_FLAGS} -Ctarget-cpu=${ARCH})
+if(ARCH)
+  list(APPEND RUST_FLAGS -Ctarget-cpu=${ARCH})
+endif()
 
 if(RUST_USE_LTO)
-  set(RUST_FLAGS ${RUST_FLAGS} -Clinker-plugin-lto -Clinker=clang -Clink-arg=-fuse-ld=lld)
+list(APPEND RUST_FLAGS -Clinker-plugin-lto -Clinker=clang -Clink-arg=-fuse-ld=lld)
 endif()
 
 if(EMSCRIPTEN_PTHREADS)

docs/.gitignore

@@ -1,2 +1,3 @@
 /site
-/docs/shards/**/*.md
+/docs/reference/shards/**/*.md
+/docs/reference/enums/**/*.md

docs/docs/.pages

@@ -1,6 +1,6 @@
 nav:
   - index.md
-  - docs
+  - reference
   - learn
   - contribute
   - About Us: https://fragcolor.xyz

docs/docs/contribute/docs/index.md

@@ -5,10 +5,10 @@ license: CC-BY-SA-4.0
 
 # Documenting the API
 
-*Note that as of 2021/10/25, the **API Documentation** for the shards is extracted from the shards binary using the infos-docs.edn script.*
+*Note that as of 2021/10/25, the **API Documentation** for the shards is extracted from the shards binary using the generate.edn script.*
 
 ```
-./src/build/shards src/tests/infos-docs.edn
+./src/build/shards docs/generate.edn
 ```
 
 If you wish to contribute, you can check out our guide on [how to start documenting](./start-documenting.md).

docs/docs/index.md

@@ -12,7 +12,7 @@ These documents will help you understand, use, and contribute to Fragcolor techn
 You can start from a high-level topic below or use the navigation links at the top.
 
 - [Shards](./learn/shards/)
-- [Built-in functions](./docs/functions/)
+- [Reference](./reference/)
 - [Contributions guides](./contribute/)
 
 *Use the search box if you're looking for something specific.*

docs/docs/learn/shards/.pages

@@ -1,5 +1,6 @@
 nav:
   - index.md
+  - introduction.md
   - what-is-shards.md
   - the-flow.md
   - working-with-data.md

docs/docs/docs/shards/index.md → docs/docs/learn/shards/introduction.md

@@ -16,7 +16,7 @@ The execution of Shards scripts is meant to be fast: the scripting language is j
 The runtime itself is completely detached.
 
 ??? note "Running code samples"
-    Many shard code samples (like for the shard [Take](/General/Take)) do not include the wire/mesh context they need to run. To run these samples you need to navigate to `../shards/docs/samples/`and use the following command to provide the necessary boilerplate code to these samples.
+    Many shard code samples (like for the shard [Take](./shards/General/Take)) do not include the wire/mesh context they need to run. To run these samples you need to navigate to `../shards/docs/samples/`and use the following command to provide the necessary boilerplate code to these samples.
 
     ```
         cd docs/samples