Merge #786

786: Publish docs of master version r=Bromeon a=Bromeon

Automatically generates docs of latest `master` version and publishes them to GitHub pages.

Co-authored-by: Jan Haller <bromeon@gmail.com>

Author: bors[bot]

.github/workflows/doc.yml

@@ -0,0 +1,108 @@
+name: Doc
+
+# To save env-var dynamically: https://github.com/actions/starter-workflows/issues/68#issuecomment-792338408
+# Persist env-var across steps: echo "var=value" >> $GITHUB_ENV
+
+# Note: search-index.js is changing every single time, even if source is not changing. This file is around 2 MB.
+# Since the doc repo is cloned prior to committing, this might cause increasingly long CI times.defaults:
+# If necessary, archive the 'gh-pages' branch from time to time, or overwrite it altogether -- doc history might not be that important.
+
+
+on:
+  push:
+    branches: [master]
+
+
+env:
+  GDNATIVE_LIB_RS_PREFIX: |-
+      //! _**Note:** This documentation refers to the [latest GitHub version](https://github.com/godot-rust/godot-rust) and is subject to change._<br>
+      //! _For stable releases, visit [docs.rs/gdnative](https://docs.rs/gdnative)._
+      //! <br><br>
+      //!
+  GDNATIVE_DOC_REPO: git@github.com:godot-rust/doc.git
+  GDNATIVE_DOC_BRANCH: gh-pages
+
+
+# In the very unlikely cases where two PRs are merged, and the first 'doc' job is still running when the 2nd 'full-ci' starts,
+# make sure the first one is awaited. Even though docs are eventually overwritten, this ensures continuitiy in the doc repo history.
+concurrency:
+  group: 'sync-doc'
+  cancel-in-progress: false
+
+
+jobs:
+  sync-doc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v2
+
+      - name: "Install Rust"
+        uses: ./.github/composite/rust
+        with:
+          rust: stable
+          components: rustfmt
+
+      - name: "Pre-process input"
+        run: |
+          mv ${GITHUB_WORKSPACE}/gdnative/src/lib.rs tmp_lib.rs
+          (echo "${GDNATIVE_LIB_RS_PREFIX}"; cat tmp_lib.rs) > ${GITHUB_WORKSPACE}/gdnative/src/lib.rs
+
+      - name: "Generate documentation"
+        uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: -p gdnative --lib --no-deps --all-features
+
+      # For email address, see https://github.community/t/github-actions-bot-email-address/17204
+      # As search-index.js changes every time, even if source hasn't changed, this will not need 'git commit --allow-empty'
+      - name: "Prepare upload"
+        run: |
+          mkdir ~/.ssh
+          echo '${{ secrets.DOC_DEPLOY_SSH_KEY }}' > ~/.ssh/id_rsa
+          chmod 700 ~/.ssh/id_rsa
+          git config --global user.name "godot-rust/doc[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          mkdir doc && cd doc
+          git clone --single-branch --branch ${GDNATIVE_DOC_BRANCH} --no-checkout ${GDNATIVE_DOC_REPO} . \
+            || (git init -b ${GDNATIVE_DOC_BRANCH} && git remote add origin ${GDNATIVE_DOC_REPO})
+
+          mv ${GITHUB_WORKSPACE}/target/doc/* .
+          mv ${GITHUB_WORKSPACE}/.github/workflows/doc/* .
+
+          GDNATIVE_VERSION=$(grep -Po '^version = "\K[^"]*' ${GITHUB_WORKSPACE}/gdnative/Cargo.toml)
+          GDNATIVE_SHORT_SHA=$(git rev-parse --short "${GITHUB_SHA}")
+
+          find gdnative -name .html -o -type f -print0 | xargs -0 sed -i 's/'"${GDNATIVE_VERSION}"'/master/g'
+
+          git add --all
+          git commit -m "Sync doc from ${GDNATIVE_SHORT_SHA}
+
+          Revision in godot-rust: ${GITHUB_SHA}"
+
+      - name: "Upload"
+        working-directory: doc
+        run: git push origin ${GDNATIVE_DOC_BRANCH}
+
+      - name: "Cleanup"
+        run: shred -u ~/.ssh/id_rsa
+
+
+
+# Possible alternative: dispatching a remote workflow
+
+#      - name: 'Dispatch remote workflow'
+#        run: >
+#          curl
+#            -X POST
+#            -H "Accept: application/vnd.github.v3+json"
+#            https://api.github.com/repos/godot-rust/doc/actions/workflows/triggered-remotely/dispatches
+#            -d '{"ref":"master"}'
+
+#      - name: Repository Dispatch
+#        uses: peter-evans/repository-dispatch@v1
+#        with:
+#          repository: godot-rust/doc
+#          token: ${{ secrets.REPO_ACCESS_TOKEN }}
+#          event-type: my-event

.github/workflows/doc/index.html

@@ -0,0 +1,7 @@
+<html>
+  <head>
+    <!-- Note: cache control not reliable through meta. The below redirection may remain cached in browsers. -->
+    <!-- Alternatively, use JS. Also, consider https://github.com/rust-lang/cargo/issues/739 in the future. -->
+    <meta http-equiv="refresh" content="0; url=/doc/gdnative" />
+  </head>
+</html>

.github/workflows/ci.yml renamed to .github/workflows/full-ci.yml

@@ -118,11 +118,13 @@ jobs:
       - name: Install LLVM
         uses: ./.github/composite/llvm
         if: ${{ matrix.os.id == 'windows-latest' }}
+      - name: Compile tests
+        run: cargo test --workspace --all-features --no-run;
       - name: Test
         run: cargo test --workspace --all-features ${{ matrix.testflags }};
 
-  check-release:
-    name: check-release-${{ matrix.os.name }}
+  build-release:
+    name: build-release-${{ matrix.os.name }}
     needs: rustfmt
     strategy:
       fail-fast: true # cancel all jobs as soon as one fails?
@@ -147,7 +149,7 @@ jobs:
       - name: Release build (check only)
         run: cargo check --release;
 
-  test-ios:
+  build-ios:
     needs: rustfmt
     #continue-on-error: ${{ matrix.rust == 'nightly' }}
     #strategy:
@@ -178,7 +180,7 @@ jobs:
           cd gdnative-sys;
           cargo dinghy --platform auto-ios-x86_64 test;
 
-  test-android:
+  build-android:
     # Note: even though Android builds for another architecture than Linux, it can reuse downloaded crates (source code, maybe 'cargo check').
     needs: rustfmt
     #continue-on-error: ${{ matrix.rust == 'nightly' }}
@@ -295,10 +297,10 @@ jobs:
       #- rustfmt
       - clippy
       - test
-      - test-ios
-      - test-android
       - integration-test-godot
-      - check-release
+      - build-release
+      - build-ios
+      - build-android
     runs-on: ubuntu-latest
     steps:
       - name: Mark the job as a success

.github/workflows/minimal-ci.yml

@@ -61,6 +61,8 @@ jobs:
       - uses: actions/checkout@v2
       - name: Install Rust
         uses: ./.github/composite/rust
+      - name: Compile tests
+        run: cargo test --workspace --all-features --no-run;
       - name: Test
         run: cargo test --workspace --all-features;
 

.github/workflows/publish.yml renamed to .github/workflows/release-version.yml

@@ -3,9 +3,10 @@ name: Publish to crates.io
 on:
   push:
     branches:
-      - '!*'
+      - '!**'
     tags:
-      - '*'
+      - '0.9.[0-9]+'
+      - '0.10.[0-9]+'
 
 defaults:
   run:

bindings_generator/src/classes.rs

@@ -67,7 +67,7 @@ pub(crate) fn generate_class_constants(class: &GodotClass) -> TokenStream {
 
     let mut class_constants: Vec<(&ConstantName, &ConstantValue)> =
         class.constants.iter().collect();
-    class_constants.sort_by(|a, b| a.0.cmp(b.0));
+    class_constants.sort_by(constant_sorter);
 
     for (name, value) in &class_constants {
         let name = format_ident!("{}", name);
@@ -88,33 +88,18 @@ pub(crate) fn generate_class_constants(class: &GodotClass) -> TokenStream {
     }
 }
 
-fn generate_enum_name(class_name: &str, enum_name: &str) -> String {
-    // In order to not pollute the API with more Result types,
-    // rename the Result enum used by Search to SearchResult
-    // to_camel_case() is used to make the enums more Rust like.
-    // DOFBlurQuality => DofBlurQuality
-    match enum_name {
-        "Result" => {
-            let mut res = String::from(class_name);
-            res.push_str(enum_name);
-            res.to_camel_case()
-        }
-        _ => enum_name.to_camel_case(),
-    }
-}
-
 pub(crate) fn generate_enums(class: &GodotClass) -> TokenStream {
-    // TODO: check whether the start of the variant name is
-    // equal to the end of the enum name and if so don't repeat it
-    // it. For example ImageFormat::Rgb8 instead of ImageFormat::FormatRgb8.
+    // TODO: check whether the start of the variant name is equal to the end of the enum name and if so, don't repeat it.
+    // For example ImageFormat::Rgb8 instead of ImageFormat::FormatRgb8.
+
     let mut enums: Vec<&Enum> = class.enums.iter().collect();
     enums.sort();
     let enums = enums.iter().map(|e| {
         let enum_name = generate_enum_name(&class.name, &e.name);
         let typ_name = format_ident!("{}", enum_name);
 
         let mut values: Vec<_> = e.values.iter().collect();
-        values.sort_by(|a, b| a.1.cmp(b.1));
+        values.sort_by(constant_sorter);
 
         let consts = values.iter().map(|(key, val)| {
             let key = key.to_uppercase();
@@ -150,3 +135,24 @@ pub(crate) fn generate_enums(class: &GodotClass) -> TokenStream {
         #(#enums)*
     }
 }
+
+fn generate_enum_name(class_name: &str, enum_name: &str) -> String {
+    // In order to not pollute the API with more Result types,
+    // rename the Result enum used by Search to SearchResult
+    // to_camel_case() is used to make the enums more Rust like.
+    // DOFBlurQuality => DofBlurQuality
+    match enum_name {
+        "Result" => {
+            let mut res = String::from(class_name);
+            res.push_str(enum_name);
+            res.to_camel_case()
+        }
+        _ => enum_name.to_camel_case(),
+    }
+}
+
+// Ensures deterministic order of constants, not dependent on inner hash-map or sort workings
+fn constant_sorter(a: &(&String, &i64), b: &(&String, &i64)) -> std::cmp::Ordering {
+    Ord::cmp(a.1, b.1) // first, sort by integer value
+        .then(Ord::cmp(a.0, b.0)) // and if equal, by name
+}

gdnative-derive/src/lib.rs

@@ -227,7 +227,7 @@ pub fn profiled(meta: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// **Important**: This needs to be added to one and only one `impl` block for a given `NativeClass`.
 ///
-/// For additional details about how `#[methods]` expands, please refer to [gdnative::methods](methods)
+/// For additional details about how `#[methods]` expands, please refer to [gdnative::methods](macro@methods)
 ///
 /// ### `#[export]`
 /// Registers the attributed function signature to be used by Godot.