HISE Logo Forum
    • Categories
    • Register
    • Login

    Looking into the hise_documentation on GitHub- any reason why a majority of the markdown files are empty for the Scripting API?

    Scheduled Pinned Locked Moved Documentation
    12 Posts 3 Posters 101 Views
    Loading More Posts
    • Oldest to Newest
    • Newest to Oldest
    • Most Votes
    Reply
    • Reply as topic
    Log in to reply
    This topic has been deleted. Only users with topic management privileges can see it.
    • Christoph HartC
      Christoph Hart @d.healey
      last edited by

      They are autogenerated and empty so that you can edit them and fill the gaps :)

      VirtualVirginV 1 Reply Last reply Reply Quote 0
      • VirtualVirginV
        VirtualVirgin @Christoph Hart
        last edited by

        @Christoph-Hart I put the Scripting API into markdown files with on file per class. Would that be useful for the Git Docs? Here is an example:

        Unlocker

        The LicenseUnlocker will aid you in managing HISEs keyfile and unlocking system.You can create an Unlocker object with Engine.createLicenseUnlocker() .

        const var Unlocker = Engine.createLicenseUnlocker();
        

        Class methods

        canExpire

        Checks if the unlocker's license system has an expiration date.

        Unlocker.canExpire()
        

        checkExpirationData

        If the unlocker has an expiration date, it will check it against the RSA encoded time string from the server.

        Unlocker.checkExpirationData( String encodedTimeString)
        

        checkMuseHub

        If you use the MuseHub SDK this will try to activate the plugin using their SDK.

        Unlocker.checkMuseHub(var resultCallback)
        

        contains

        Checks if the string contains the given substring.

        Unlocker.contains(String otherString)
        

        getLicenseKeyFile

        Returns the license key file as File object.

        Unlocker.getLicenseKeyFile()
        

        getRegisteredMachineId

        Returns the machine ID that is encoded into the license file. This does not look in the encrypted blob, but just parses the header string.

        Unlocker.getRegisteredMachineId()
        

        getUserEmail

        Returns the user email that was used for the registration.

        Unlocker.getUserEmail()
        

        isUnlocked

        Checks if the registration went OK.

        Unlocker.isUnlocked()
        

        isValidKeyFile

        Checks if the possibleKeyData might contain a key file.

        Unlocker.isValidKeyFile(var possibleKeyData)
        

        keyFileExists

        Checks whether the key file exists.

        Unlocker.keyFileExists()
        

        loadKeyFile

        This checks if there is a key file and applies it.

        Unlocker.loadKeyFile()
        

        setProductCheckFunction

        Sets a function that performs a product name check and expects to return true or false for a match.

        Unlocker.setProductCheckFunction(var f)
        

        writeKeyFile

        Writes the key data to the location.

        Unlocker.writeKeyFile( String keyData)
        

        You can listen to my orchestral mockups here:
        https://www.virtualvirgin.net/

        d.healeyD 1 Reply Last reply Reply Quote 0
        • VirtualVirginV
          VirtualVirgin
          last edited by

          Ok, the uploads doesn't like .md format so I just put it in a text file:

          Unlocker.txt

          You can listen to my orchestral mockups here:
          https://www.virtualvirgin.net/

          1 Reply Last reply Reply Quote 0
          • d.healeyD
            d.healey @VirtualVirgin
            last edited by

            @VirtualVirgin said in Looking into the hise_documentation on GitHub- any reason why a majority of the markdown files are empty for the Scripting API?:

            I put the Scripting API into markdown files with on file per class. Would that be useful for the Git Docs? Here is an example:

            Isn't that the same as the autogenerated docs? https://docs.hise.audio/scripting/scripting-api/unlocker/index.html

            Libre Wave - Freedom respecting instruments and effects
            My Patreon - HISE tutorials
            YouTube Channel - Public HISE tutorials

            VirtualVirginV 1 Reply Last reply Reply Quote 0
            • VirtualVirginV
              VirtualVirgin @d.healey
              last edited by

              @d-healey I hope so! That is what I made them from. I just wanted to be able to use the Scripting API in markdown format, but your response makes me think that I am lacking context or missing something obvious?

              You can listen to my orchestral mockups here:
              https://www.virtualvirgin.net/

              d.healeyD 1 Reply Last reply Reply Quote 0
              • d.healeyD
                d.healey @VirtualVirgin
                last edited by

                @VirtualVirgin said in Looking into the hise_documentation on GitHub- any reason why a majority of the markdown files are empty for the Scripting API?:

                I am lacking context or missing something obvious?

                Or I am :) I'm not sure what your goal is.

                Libre Wave - Freedom respecting instruments and effects
                My Patreon - HISE tutorials
                YouTube Channel - Public HISE tutorials

                VirtualVirginV 1 Reply Last reply Reply Quote 0
                • VirtualVirginV
                  VirtualVirgin @d.healey
                  last edited by

                  @d-healey Just that if the markdown files for the Documentation on GitHub has mostly blank files, maybe these are useful? Or maybe I am not understanding the purpose of the markdown files on the GitHub site.

                  You can listen to my orchestral mockups here:
                  https://www.virtualvirgin.net/

                  d.healeyD 1 Reply Last reply Reply Quote 0
                  • d.healeyD
                    d.healey @VirtualVirgin
                    last edited by

                    @VirtualVirgin The documentation on the docs website is autogenerated from the comments in the HISE source code. If you want to change that auto-generated documentation to say something else then you can add your changes to the markdown files.

                    There is no advantage to putting the autogenerated content we already have into the markdown file, because then if something changes in the source code the documentation won't automatically follow it.

                    Libre Wave - Freedom respecting instruments and effects
                    My Patreon - HISE tutorials
                    YouTube Channel - Public HISE tutorials

                    Christoph HartC 1 Reply Last reply Reply Quote 0
                    • Christoph HartC
                      Christoph Hart @d.healey
                      last edited by

                      Aw poor @VirtualVirgin that was half an hour that you'll never get back, sorry for being not clear enough.

                      So basically what happens is that I'm taking the markdown files from GitHub to build the HISE docs website. The documentation generator takes some autogenerated code and merges it with the additional text from GitHub - this way it stays always up to date and the formatting is consistent.

                      Now the problem was at some point (and we discussed this at some HISE meetup) that the user engagement with the task of contributing to the HISE documentation is mostly hindered by the complicated system that people have to follow in order to write the docs so we came up with the solution that the HISE documentation generator just creates these empty markdown files for all undocumented API methods that have the proper file name / folder scheme so that they will show up later in the docs. From there, people can just edit the empty files to add more context, code examples or more thorough explanations than the one liner API help that is being extracted from the HISE source code.

                      So what looks like a bug to you - empty text files - is actually a feature that is supposed to lower the barrier for user contributions.

                      VirtualVirginV 1 Reply Last reply Reply Quote 1
                      • VirtualVirginV
                        VirtualVirgin @Christoph Hart
                        last edited by VirtualVirgin

                        @Christoph-Hart said in Looking into the hise_documentation on GitHub- any reason why a majority of the markdown files are empty for the Scripting API?:

                        Aw poor @VirtualVirgin that was half an hour that you'll never get back

                        "Aw poor @VirtualVirgin that was half an hour that you'll never get back"

                        No worries! Was learning how to generate markdown files from text.
                        I made text files of all of the classes in the API, then ran a python script to transform it to markdown. Just a learning experience. I then went on the generate JSON for the API with the following schema:

                        {
                          "$schema": "https://json-schema.org/draft/2020-12/schema",
                          "title": "Scripting API Method",
                          "type": "object",
                          "properties": {
                            "class": {
                              "type": "string",
                              "description": "The class this method belongs to."
                            },
                            "method": {
                              "type": "string",
                              "description": "The method name."
                            },
                            "description": {
                              "type": "string",
                              "description": "A description of what the method does."
                            },
                            "syntax": {
                              "type": "string",
                              "description": "The usage syntax string for the method."
                            },
                            "parameters": {
                              "type": "array",
                              "description": "List of method parameters.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string",
                                    "description": "The parameter name."
                                  },
                                  "type": {
                                    "type": "string",
                                    "description": "The parameter type."
                                  },
                                  "optional": {
                                    "type": "boolean",
                                    "description": "Whether the parameter is optional."
                                  },
                                  "description": {
                                    "type": "string",
                                    "description": "A description of the parameter."
                                  }
                                },
                                "required": ["name", "type", "optional", "description"],
                                "additionalProperties": false
                              }
                            },
                            "returns": {
                              "type": "string",
                              "description": "The return type of the method."
                            },
                            "examples": {
                              "type": "array",
                              "description": "Code examples demonstrating usage.",
                              "items": {
                                "type": "string"
                              }
                            }
                          },
                          "required": [
                            "class",
                            "method",
                            "description",
                            "syntax",
                            "parameters",
                            "returns"
                          ],
                          "additionalProperties": false
                        }
                        

                        Which makes this for example:

                        [
                          {
                            "class": "Array",
                            "method": "clear",
                            "description": "Clears the array.",
                            "syntax": "Array.clear()",
                            "parameters": [],
                            "returns": "",
                            "examples": [
                              "const var arr = []; // Declare an array\n\n// preallocate 10 elements, do this if you\n// know how many elements you are about to insert\narr.reserve(10); \n\nfor(i = 0; i < 10; i++)\n{\n\t// Add an element to the end of the array\n\tarr.push(Math.randInt(0, 1000));\n}\n\nConsole.print(trace(arr)); // [ 523, 5, 76, 345, 765, 45, 977, 223, 44, 54]\n\narr.clear();\n\nConsole.print(trace(arr)); // []"
                            ]
                          },
                          {
                            "class": "Array",
                            "method": "clone",
                            "description": "Creates a deep copy of the array.",
                            "syntax": "Array.clone()",
                            "parameters": [],
                            "returns": "A deep copy of the array.",
                            "examples": [
                              "const arr1 = [0, 1];\n\nvar arr2 = arr1;\n\n// Changing any element in arr2 will also change it in arr1\narr2[0] = 22;\nConsole.print(trace(arr1)); // [22, 1]\n\n// Reset the element 0 back to 0\narr1[0] = 0;\n\n// Cloning the array creates a new dataset in memory, separate from the original array\narr2 = arr1.clone();\nConsole.print(trace(arr1));\narr2[0] = 22;\nConsole.print(trace(arr2));"
                            ]
                          },
                        

                        I'm sure this is all elementary for you and David, but I'm just learning how to do some these data formats and transformations with parsers etc.

                        You can listen to my orchestral mockups here:
                        https://www.virtualvirgin.net/

                        1 Reply Last reply Reply Quote 1
                        • First post
                          Last post

                        18

                        Online

                        2.0k

                        Users

                        12.6k

                        Topics

                        109.6k

                        Posts