-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Update README.md * change to main server * Update important-caveats.md * Update getting-started.md * Update for-automate-composers.md * Update viewing-results.md * Update viewing-results.md * Update for-automate-composers.md * Create for-automate-users.md Reflects the simplification of language * Update config.js * Delete automate/for-automate-composers.md * Update for-function-authors.md * Update create-automation.md * Update update-automation.md * Update config.js * Create public-functions * Create public-functions.md * Delete automate/public-functions * Update public-functions.md * Update public-functions.md * Update public-functions.md * Update public-functions.md * Update for-function-authors.md * Update create-function.md * Update function-testing.md * Update documenting.md * Update release-function-version.md * Update release-function-version.md * Update demos.md * Update demos.md * Update feedback.md * Update roadmap.md * Update roadmap.md * Update troubleshooting.md * Update known-issues.md * Update frequently-asked-questions.md * Update config.js * Update public-functions.md * Update viewing-results.md * Update release-function-version.md * Update troubleshooting.md
- Loading branch information
1 parent
044ddef
commit 5b0b9f0
Showing
21 changed files
with
654 additions
and
474 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,15 @@ | ||
| # Speckle Automate Beta | ||
| ::: tip 🚧 NOTE | ||
| Speckle Automate is in an accessible beta phase and restricted to the Speckle development server. These docs are a work in progress and are updated regularly. | ||
| # Speckle Automate Public Beta | ||
|
|
||
| ::: tip 🚧 NOTE | ||
| Speckle Automate has entered the public beta phase and is now available on the Speckle production server: [app.speckle.systems](https://app.speckle.systems). These docs are a work in progress and are updated regularly to reflect the latest features and improvements. | ||
| ::: | ||
|
|
||
| This documentation is designed to assist Speckle Automate users in creating and managing automation. As a Speckle user, you can now act as an **Automator**, leveraging public functions and creating custom workflows to streamline tasks and enhance productivity. | ||
|
|
||
| This mini documentation is designed to assist beta testers of Speckle Automate, focusing on the **Function Author** and **Automation Composer** personas. Your feedback is essential in refining these roles within the platform, enhancing functionality, and ensuring a user-friendly experience. | ||
| ### Key Highlights: | ||
| - **Public Functions**: Available to all users on [app.speckle.systems](https://app.speckle.systems). | ||
| - **Private Functions**: Creatable and manageable within Workspaces. | ||
| - **Unified Hosting**: All data, functions, and automations are hosted on the main Speckle server. | ||
| - **Collaboration**: Workspace members can use public and private functions to create automations collaboratively. | ||
|
|
||
| We will continuously improve these documentation details as things develop; there may be occasions when development outpaces the documentation. If you have any questions, please reach out to us on the [Speckle Community Forum: Automate](https://speckle.community/c/making-speckle/insiders-automate/27). | ||
| We are continuously improving the documentation. As Speckle Automate evolves, there may be occasions when development temporarily outpaces the documentation. If you have any questions, please contact us on the [Speckle Community Forum: Automate](https://speckle.community/c/making-speckle/insiders-automate/27). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,62 +1,69 @@ | ||
| # Creating Functions | ||
|
|
||
| If you have your verified account on latest.speckle.systems, navigate to [latest.speckle.systems/functions](https://latest.speckle.systems/functions). | ||
|
|
||
| You will now see above the Functions Library. In the top right, there is a new function button: | ||
| If you have a verified account on [app.speckle.systems](https://app.speckle.systems), navigate to [app.speckle.systems/functions](https://app.speckle.systems/functions). | ||
|
|
||
| You will see the Functions Library. In the top right, there is a **New Function** button: | ||
|  | ||
|
|
||
| This will launch the function creation wizard | ||
|
|
||
| 1. **Authorise GitHub:** Required only the first time. | ||
|
|
||
|  | ||
|
|
||
| ::: tip 💡 Authorized OAuth Apps | ||
| You will find Speckle Automate in your Github account Authorized OAuth Apps. Access can be revoked at any time, but will be necessary to publish new functions. | ||
|
|
||
|  | ||
|
|
||
| ::: | ||
|
|
||
| 2. **Choose a template**: We are launching with Python and C# templates. These reflect our best-supported Speckle SDKs, **speckle-sharp** and **specklepy**. Each of our main SDKs includes the Automate SDK for that language. | ||
| 3. **Define your function.** (Some of these details can be edited later) | ||
| 1. **Choose an avatar/logo/icon** [optional]: This will be displayed in the functions list | ||
| 2. **Choose a Name** [required]: This doesn’t need to be unique, but all functions will be a single list during the beta stages. The search filter will use the function name alone; it could be helpful if it identifies you as an author/company and the name/function intent. *e.g. SolarFarmLayout by Solarcorp* | ||
| 3. **Add a description** [required]: This will be the short description used in the function list. The description supports basic Markdown if you wish to add markup. | ||
| 4. **Identify source application data supported** [optional]: This may be helpful when defining Automations | ||
| 5. **Add Tags** [optional]: A list of terms to categorise your function further. Multi-word tags should use _ or - characters. *e.g. Solar_Panels* | ||
| 6. **~~Select a Github Organization** [optional]: This is only relevant if you want to publish as an organization and are a member of one.~~ | ||
| 7. **Click Next**: All being well, the wizard will create your function project on GitHub. | ||
|
|
||
| ::: tip 🧙♂️ Wizard Actions | ||
| You will see that the wizard handles a lot of scaffolding for you. You can navigate to GitHub and see that the template project has been cloned under your repositories: | ||
|
|
||
|  | ||
|
|
||
| A GitHub action has been created for you; the specification for it is defined in `.github/workflows/**main.yml**` | ||
|
|
||
|  | ||
|
|
||
| It also has injected two environmental variables as repository secrets for the interaction with the Automate API `SPECKLE_FUNCTION_ID` and `SPECKLE_FUNCTION_TOKEN`: | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ::: | ||
|
|
||
| ::: tip 💡 Note | ||
| Choose whatever Project restrictions you wish, but it must be Public for now. | ||
| ::: | ||
|
|
||
| </aside> | ||
| 4. Your function has been created! 🥳 At this point, the template can be edited and amended to suit your own business logic. | ||
|
|
||
|  | ||
|
|
||
| 5. You can follow the links provided to: | ||
| 1. **Open the repo:** this is a link to the project on GitHub | ||
| 2. **Open in codespace:** You can get coding immediately in a virtual machine operating in a container at GitHub. Remember that any changes you make must be pushed to your project. | ||
| 3. **Go to function**: This will navigate you to your functions page within Speckle Automate. | ||
| 6. Your function will only appear in the [functions list](https://automate.speckle.dev/functions) once a first Release has been made. | ||
| This launches the function creation wizard. | ||
|
|
||
| --- | ||
|
|
||
| ## Steps to Create a Function | ||
|
|
||
| 1. **Authorise GitHub** | ||
| Required only the first time. | ||
|  | ||
|
|
||
| ::: tip 💡 **Authorized OAuth Apps** | ||
| Speckle Automate will appear under your GitHub account's Authorized OAuth Apps. Access can be revoked at any time but will be necessary to publish new functions. | ||
|  | ||
| ::: | ||
|
|
||
| 2. **Choose a Template** | ||
| We currently offer Python and C# templates, reflecting our best-supported SDKs (**specklepy** and **speckle-sharp**). Each includes the Automate SDK for its respective language. | ||
|
|
||
| 3. **Define Your Function** | ||
| Some details can be edited later: | ||
| - **Avatar/Logo/Icon** [optional]: Displayed in the functions list. | ||
| - **Name** [required]: Does not need to be unique. Use a descriptive name to help identify the function and its purpose, e.g., `SolarFarmLayout by SolarCorp`. | ||
| - **Description** [required]: A short Markdown-supported description used in the functions list. | ||
| - **Source Application Data Supported** [optional]: Indicate which source applications your function is designed for. | ||
| - **Tags** [optional]: You can further categorise your function with single or multi-word tags, e.g., `Solar_Panels`. | ||
| - **Click Next**: The wizard will create your function project on GitHub. | ||
|
|
||
| ::: tip 🧙♂️ **Wizard Actions** | ||
| The wizard handles scaffolding for you: | ||
| - Clones the template project into your repositories. | ||
|  | ||
| - Creates a GitHub action (`.github/workflows/main.yml`) for build and deployment. | ||
|  | ||
| - Injects API interaction environment variables (`SPECKLE_FUNCTION_ID` and `SPECKLE_FUNCTION_TOKEN`). | ||
|  | ||
| ::: | ||
|
|
||
| 4. **Repository Management** | ||
| The function wizard creates a GitHub repository under your account. | ||
| - **Public vs Private**: Whether to keep this repository public or private depends on your team's open-source or source-available development approach. Speckle Automate supports both public and private repositories. | ||
| - **Personal or Organisational Accounts**: Depending on your setup and collaboration needs, you can publish functions from either your personal GitHub account or an organisation's account. | ||
|
|
||
| ::: tip 💡 **Important** | ||
| Carefully manage repository access based on your team's workflows and requirements. | ||
| ::: | ||
|
|
||
| 5. **Finalise Your Function** | ||
| Once created, the function template can be edited and tailored to your business logic. | ||
|  | ||
|
|
||
| 6. **Next Steps** | ||
| From the success page, you can: | ||
| - **Open the Repository**: View the project on GitHub. | ||
| - **Open in Codespace**: Start coding immediately in a virtual environment. Remember to push changes back to GitHub. | ||
| - **Go to Function**: Navigate to your function’s page within Speckle Automate. | ||
|
|
||
| 7. **Make a Release** | ||
| After making the first release on GitHub, your function will only appear in the Functions Library. | ||
|
|
||
| --- | ||
|
|
||
| With these steps, your function is ready for further development, automation, and collaboration! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,26 @@ | ||
| # Documenting your function | ||
| Your function’s `README.md` will be published to its dedicated Automate page. This is your opportunity to communicate the key functionality, limitations, and detailed instructions for the function’s inputs to automation composers. | ||
| # Documenting Your Function | ||
|
|
||
| Later, this will be your opportunity to market why your function is the go-to solution for quality control, solar farm layouts, or Pokemon detection for Speckle. It is also a great way to seek collaborators. | ||
| Your function’s `README.md` will be published to its dedicated Automate page. This is your opportunity to communicate the key functionality, limitations, and detailed instructions for the function’s inputs to your team and organisation. | ||
|
|
||
| You can choose how detailed you would want to document the functional logic, so long as it is abundantly clear what it results in given what source data. | ||
| Speckle Automate’s function listing will display with full Markdown support, including relevant imagery, etc. | ||
| Clear documentation is critical for: | ||
|
|
||
|  | ||
| Example of the Readme as displayed in a function listing. | ||
| - Helping your team and collaborators understand how to use the function effectively. | ||
| - Ensuring consistency and transparency when sharing functions within a Workspace. | ||
| - Providing detailed instructions that reduce confusion and the need for additional support. | ||
|
|
||
| ## Key Points for Documentation | ||
|
|
||
| - **Clarity and Precision**: Ensure it is abundantly clear what your function produces given specific source data and input parameters. | ||
| - **Detail as Needed**: Provide enough detail about the function’s purpose, logic, and limitations to enable your team to use it effectively. | ||
| - **Markdown Support**: Speckle Automate’s function listing supports full Markdown, allowing you to include relevant imagery, links, and formatting for a professional and functional presentation. | ||
|
|
||
| ### Example | ||
|
|
||
| Below is an example of how a well-documented `README.md` might appear on a function listing: | ||
|
|
||
|  | ||
| *Example of the README as displayed in a function listing.* | ||
|
|
||
| --- | ||
|
|
||
| Clear and thorough documentation ensures your function is easy to understand, use, and maintain—ultimately benefiting your team and organisation. Take the time to make it count! |
Oops, something went wrong.