From 8db2115d7a1222b5c30e56bdd6dfab58909d8399 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 18 Mar 2024 16:08:50 -0700 Subject: [PATCH 01/35] initial draft of updated readme --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 73 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 26d2a068..7f90ff45 100644 --- a/README.md +++ b/README.md @@ -4,22 +4,84 @@ This repo contains the technical reference manual for the Bonsai visual programming language, in addition to articles and examples that document the collective knowledge of the Bonsai user community. -# Would you like to contribute to this repo? +> [!NOTE] +> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo. For instance, https://github.com/bonsai-rx/machinelearning hosts the documentation for the Bonsai Machine Learning package. The instructions below apply to both documentation for the base Bonsai library as well as new packages. -## Step-by-step guide to getting started as a contributor +Documentation is built using DocFx, a static site generator that can automatically generate API documentation for .NET projects, and deployed using a Github Actions workflow on Github Pages. -1. Fork the "develop" branch of this repository. -2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.59). -3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website. -4. If you are working on multiple articles at once, create a descriptively named branch of your fork of the repo for each article. We recommend creating an issue for each article (if it does not already exist), and name the branch `issue-###` where `###` is the issue number. -5. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork of the repo and create a PR to merge that branch with the "develop" branch of this original repo. Because the "develop" branch was created explicitly to aid collaboration between contributors, pull requests to this branch will be accepted and merged rapidly (at least once a week). -6. Once a piece of documentation has been polished, and at least two community members agree that it is ready for a final review, create a pull request to merge with the "main" branch of this repo. At this point, @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with "main" will be approved and the contribution will be published on the [publicly accessible Bonsai documentation website](https://bonsai-rx.org/docs-wip/). +# Would you like to contribute to documentation? -## Contributor Style Guide +## Step by step guide to contributing to existing documentation + +These instructions apply to repos that already have a Doc-fx website created in the repo. + +1. Fork the "main" branch of the repository you want to contribute documentation to. +2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.75.3). +3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you make changes. +4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork of the repo and create a pull request to merge that branch with the "main" branch of the original repo. +5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with "main" will be approved and the contribution will be published. + + +## Step by step guide to setting up new documentation + +For packages without existing documentation, a new Doc-fx website needs to be initialized. + +1) In Windows Powershell, setup a local installation of DocFX in the repo with the following commands (executed in the root directory of the repo). -### Why use the "develop" branch? +``` +dotnet new tool-manifest # if you are setting up this repo for the same time +dotnet tool install --local docfx --version 2.75.3 +``` + +2) Create a new “docs” folder to host the documentation files. Navigate to folder and initialise a new doc-fx website with the following command. + +``` +dotnet docfx init +``` +3) Select these options for the new website +``` +Name (mysite): Bonsai - Package Name +Generate .NET API documentation? [y/n] (y): y +.NET projects location (src): src +Markdown docs location (docs): articles +Enable site search? [y/n] (y): y +Enable PDF? [y/n] (y): n +``` +4) This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. From here on out we just need to make a few tweaks to the configuration as well as copy over some files. + +5) In the "docs" folder, create these folders +articles - this will host markdown files for various articles +images - this will host images for the website +workflows - this will host .bonsai files for example workflows. + +6) Copy over these files from a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/), and place them in the root folder of the repo. Amend the files as necessary + +* .github folder - this includes a workflows/docs.yml file that is a Github Actions workflow recipe to build the docfx website. +If one already exists, make sure that it is updated to the latest version and change the package name parameters + +* .bonsai folder -this includes the files necessary to build a Bonsai environment on Github Actions. + * The config.yml file in the .bonsai folder needs to be amended to include any packages that are necessary for running the SVG export for sample Bonsai workflows on Github Actions (see below for more details). + * The new Bonsai package itself does not need to be included. + +* .gitignore file - this needs to be updated to ignore some of the new workflow files (like the .bonsai packages env) + +The rest of the folders and files go into the docs folder +* docs\filter.yml file - this filters out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported) +* docs\.gitignore file - this filters out the _site folder that is generated during local preview +* docs\favicon.ico and docs\logo.svg files- site logos +* docs\workflows\.gitignore file - this ignore bonsai layout files and svg files +* docs\build.ps1 file - this script calls upon the export images + * amend the line in the file to the new package name and source location. +* docs\template\public folder- this should contain main.css and main.js which are patches for the default template and utilise the docfx-tools submodule. + * amend main.js to change the github link to the current repository. + + + +# Editing Articles + + +## Contributor Style Guide -The "develop" branch is specifically created so that contributors can quickly commit drafts of documentation and collaborate with other community members in order to edit and polish documentation contributions. ### Re-use/update existing documentation From d7b527d0a5035debbd765b1db41e90481140fc7d Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 18 Mar 2024 16:29:29 -0700 Subject: [PATCH 02/35] updated formatting --- README.md | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 7f90ff45..2b8f91bc 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ For packages without existing documentation, a new Doc-fx website needs to be in 1) In Windows Powershell, setup a local installation of DocFX in the repo with the following commands (executed in the root directory of the repo). ``` -dotnet new tool-manifest # if you are setting up this repo for the same time +dotnet new tool-manifest dotnet tool install --local docfx --version 2.75.3 ``` @@ -47,14 +47,14 @@ Markdown docs location (docs): articles Enable site search? [y/n] (y): y Enable PDF? [y/n] (y): n ``` -4) This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. From here on out we just need to make a few tweaks to the configuration as well as copy over some files. +This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. From here on out we just need to make a few tweaks to the configuration as well as copy over some files. -5) In the "docs" folder, create these folders -articles - this will host markdown files for various articles -images - this will host images for the website -workflows - this will host .bonsai files for example workflows. +4) In the "docs" folder, create these folders. +* articles - this will host markdown files for various articles +* images - this will host images for the website +* workflows - this will host .bonsai files for example workflows. -6) Copy over these files from a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/), and place them in the root folder of the repo. Amend the files as necessary +5) Copy over these files from a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/), and place them in the root folder of the repo. Amend the files as necessary * .github folder - this includes a workflows/docs.yml file that is a Github Actions workflow recipe to build the docfx website. If one already exists, make sure that it is updated to the latest version and change the package name parameters @@ -65,16 +65,24 @@ If one already exists, make sure that it is updated to the latest version and ch * .gitignore file - this needs to be updated to ignore some of the new workflow files (like the .bonsai packages env) -The rest of the folders and files go into the docs folder -* docs\filter.yml file - this filters out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported) -* docs\.gitignore file - this filters out the _site folder that is generated during local preview -* docs\favicon.ico and docs\logo.svg files- site logos -* docs\workflows\.gitignore file - this ignore bonsai layout files and svg files -* docs\build.ps1 file - this script calls upon the export images +6) Copy the rest of these folders and files into the "docs" folder +* docs/filter.yml file - this filters out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported) +* docs/.gitignore file - this filters out the _site folder that is generated during local preview +* docs/favicon.ico and logo.svg - files for site logo and bookmark icon +* docs/workflows/.gitignore file - this ignore bonsai layout files and svg files +* docs/build.ps1 file - this script is used to export images for sample workflows * amend the line in the file to the new package name and source location. -* docs\template\public folder- this should contain main.css and main.js which are patches for the default template and utilise the docfx-tools submodule. +* docs/template/public folder- this should contain main.css and main.js which are patches for the default template and utilise the docfx-tools submodule. * amend main.js to change the github link to the current repository. +7) The docfx-tools submodule adds scripts for automating SVG export from sample workflows and patches the docfx CSS templates to add workflow containers. + +to add it to the first time to a new docfx website, use +``` +git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai +``` +The main.css and main.js should already be modified but if not more information on how to modify them can be found at https://github.com/bonsai-rx/docfx-tools. + # Editing Articles From 1ea57b0e0c093d16cf8cb448bb9e3fac8a5af8de Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 18 Mar 2024 22:59:01 -0700 Subject: [PATCH 03/35] updated readme with how to setup a new docfx website --- README.md | 96 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 78 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 2b8f91bc..8a9d87fe 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,13 @@ This repo contains the technical reference manual for the Bonsai visual programm > [!NOTE] > This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo. For instance, https://github.com/bonsai-rx/machinelearning hosts the documentation for the Bonsai Machine Learning package. The instructions below apply to both documentation for the base Bonsai library as well as new packages. -Documentation is built using DocFx, a static site generator that can automatically generate API documentation for .NET projects, and deployed using a Github Actions workflow on Github Pages. +Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using a Github Actions workflow on Github Pages. # Would you like to contribute to documentation? ## Step by step guide to contributing to existing documentation -These instructions apply to repos that already have a Doc-fx website created in the repo. +These instructions apply to repos that already have a DocFx website created. 1. Fork the "main" branch of the repository you want to contribute documentation to. 2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.75.3). @@ -24,16 +24,16 @@ These instructions apply to repos that already have a Doc-fx website created in ## Step by step guide to setting up new documentation -For packages without existing documentation, a new Doc-fx website needs to be initialized. +For packages without existing documentation, a new DocFx website needs to be initialized. -1) In Windows Powershell, setup a local installation of DocFX in the repo with the following commands (executed in the root directory of the repo). +1) In Windows Powershell, setup a local installation of DocFx in the repo with the following commands (executed in the root directory of the repo). ``` dotnet new tool-manifest dotnet tool install --local docfx --version 2.75.3 ``` -2) Create a new “docs” folder to host the documentation files. Navigate to folder and initialise a new doc-fx website with the following command. +2) Create a new “docs” folder to host the documentation files. Navigate to folder and initialise a new DocFx website with the following command. ``` dotnet docfx init @@ -47,16 +47,74 @@ Markdown docs location (docs): articles Enable site search? [y/n] (y): y Enable PDF? [y/n] (y): n ``` -This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. From here on out we just need to make a few tweaks to the configuration as well as copy over some files. +This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. From here on out we just need to make a few tweaks to docfx.json as well as copy over some additional files and folders. -4) In the "docs" folder, create these folders. -* articles - this will host markdown files for various articles -* images - this will host images for the website +4) Configuring docfx.json - most of the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). A few of the important changes are explained here (not exhaustive). + +``` +"metadata": [ + { + "filter": "filter.yml" + } +] + - this uses the filter.yml file to filter out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported). + +"resource": { + "files": [ + "logo.svg", + "favicon.ico", + "images/**", + "workflows/**" + ] +} + +- any additional files that are to be used in the docs needs to be added here + + +"globalMetadata": { + "_appName": "Bonsai - PackageName", + "_appTitle": "Bonsai.PackageName", + "_appFooter": "© 2024 Bonsai Foundation CIC and Contributors. Made with docfx", + "_gitContribute": { + "repo": "https://github.com/bonsai-rx/PackageName", + "branch": "main", + "apiSpecFolder": "apidoc" + } +} + +- change PackageName and github link to the repo being worked on. + +"template": [ + "default", + "modern", + "bonsai/template", + "template" +] +- this applies CSS patches to enable custom workflow containers + +"xref": [ + "https://bonsai-rx.org/docs/xrefmap.yml", + "https://horizongir.github.io/reactive/xrefmap.yml" +] +- this allows for linking of operators and properties across the different Bonsai docs websites + + +``` + + +5) In the "docs" folder, create these folders. + +``` +* articles - this will host markdown files for various articles that will go into the "Manual" documentation +* apidoc - this will host markdown files for individual Bonsai operators or properties that will go into the "Reference" documentation. +* images - this will host images for the website. * workflows - this will host .bonsai files for example workflows. +``` -5) Copy over these files from a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/), and place them in the root folder of the repo. Amend the files as necessary +6) Copy over these files from a repo that has been recently updated, and place them in the root folder of the repo. Amend the files as necessary. -* .github folder - this includes a workflows/docs.yml file that is a Github Actions workflow recipe to build the docfx website. +``` +* .github folder - this includes a workflows/docs.yml file that is a Github Actions workflow recipe to build the DocFx website. If one already exists, make sure that it is updated to the latest version and change the package name parameters * .bonsai folder -this includes the files necessary to build a Bonsai environment on Github Actions. @@ -64,9 +122,12 @@ If one already exists, make sure that it is updated to the latest version and ch * The new Bonsai package itself does not need to be included. * .gitignore file - this needs to be updated to ignore some of the new workflow files (like the .bonsai packages env) +``` + +7) Copy the rest of these folders and files into the "docs" folder -6) Copy the rest of these folders and files into the "docs" folder -* docs/filter.yml file - this filters out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported) +``` +* docs/filter.yml file - this filters out obsolete operators from being included in API documentation. * docs/.gitignore file - this filters out the _site folder that is generated during local preview * docs/favicon.ico and logo.svg - files for site logo and bookmark icon * docs/workflows/.gitignore file - this ignore bonsai layout files and svg files @@ -74,14 +135,13 @@ If one already exists, make sure that it is updated to the latest version and ch * amend the line in the file to the new package name and source location. * docs/template/public folder- this should contain main.css and main.js which are patches for the default template and utilise the docfx-tools submodule. * amend main.js to change the github link to the current repository. +``` -7) The docfx-tools submodule adds scripts for automating SVG export from sample workflows and patches the docfx CSS templates to add workflow containers. - -to add it to the first time to a new docfx website, use +8) Add the docfx-tools submodule. This submodule contains scripts for automating SVG export from sample workflows and patches the DocFx CSS templates to add workflow containers. ``` git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai ``` -The main.css and main.js should already be modified but if not more information on how to modify them can be found at https://github.com/bonsai-rx/docfx-tools. + @@ -99,7 +159,7 @@ When working on an article, first check [the old documentation](https://bonsai-r To include a figure or image in an article: - save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg` - - add the figure/image to the **images** folder in this repo + - add the figure/image to the **images** folder in the repo ### Standard formatting for operators and operator properties From 7c18b4fee3d74a28a6ed056827631f543c4c5967 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Tue, 19 Mar 2024 16:51:47 -0700 Subject: [PATCH 04/35] edited code blocks --- README.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8a9d87fe..82bfb52d 100644 --- a/README.md +++ b/README.md @@ -28,18 +28,18 @@ For packages without existing documentation, a new DocFx website needs to be ini 1) In Windows Powershell, setup a local installation of DocFx in the repo with the following commands (executed in the root directory of the repo). -``` +```powershell dotnet new tool-manifest dotnet tool install --local docfx --version 2.75.3 ``` 2) Create a new “docs” folder to host the documentation files. Navigate to folder and initialise a new DocFx website with the following command. -``` +```powershell dotnet docfx init ``` 3) Select these options for the new website -``` +```powershell Name (mysite): Bonsai - Package Name Generate .NET API documentation? [y/n] (y): y .NET projects location (src): src @@ -51,14 +51,17 @@ This creates a docfx.json file in the "docs" folder that hosts the configuration 4) Configuring docfx.json - most of the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). A few of the important changes are explained here (not exhaustive). -``` +```yml "metadata": [ { "filter": "filter.yml" } ] - - this uses the filter.yml file to filter out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported). +``` +This uses the filter.yml file to filter out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported). + +```yml "resource": { "files": [ "logo.svg", @@ -67,10 +70,11 @@ This creates a docfx.json file in the "docs" folder that hosts the configuration "workflows/**" ] } +``` -- any additional files that are to be used in the docs needs to be added here - +List any additional files/folders that are to be used in the docs needs to be added here +```yml "globalMetadata": { "_appName": "Bonsai - PackageName", "_appTitle": "Bonsai.PackageName", @@ -81,30 +85,31 @@ This creates a docfx.json file in the "docs" folder that hosts the configuration "apiSpecFolder": "apidoc" } } +``` +Change PackageName and github link to the repo being worked on and add footer information -- change PackageName and github link to the repo being worked on. - +```yml "template": [ "default", "modern", "bonsai/template", "template" ] -- this applies CSS patches to enable custom workflow containers +``` +This applies CSS patches to enable custom workflow containers +```yml "xref": [ "https://bonsai-rx.org/docs/xrefmap.yml", "https://horizongir.github.io/reactive/xrefmap.yml" ] -- this allows for linking of operators and properties across the different Bonsai docs websites - - ``` +This allows for cross reference of operators and properties across the different Bonsai docs websites 5) In the "docs" folder, create these folders. -``` +```markdown * articles - this will host markdown files for various articles that will go into the "Manual" documentation * apidoc - this will host markdown files for individual Bonsai operators or properties that will go into the "Reference" documentation. * images - this will host images for the website. @@ -113,7 +118,7 @@ This creates a docfx.json file in the "docs" folder that hosts the configuration 6) Copy over these files from a repo that has been recently updated, and place them in the root folder of the repo. Amend the files as necessary. -``` +```markdown * .github folder - this includes a workflows/docs.yml file that is a Github Actions workflow recipe to build the DocFx website. If one already exists, make sure that it is updated to the latest version and change the package name parameters @@ -126,7 +131,7 @@ If one already exists, make sure that it is updated to the latest version and ch 7) Copy the rest of these folders and files into the "docs" folder -``` +```markdown * docs/filter.yml file - this filters out obsolete operators from being included in API documentation. * docs/.gitignore file - this filters out the _site folder that is generated during local preview * docs/favicon.ico and logo.svg - files for site logo and bookmark icon From d835e6e72a2d2ac4e8a218a2c1414ac64256371c Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 22 Mar 2024 16:31:56 -0700 Subject: [PATCH 05/35] added section on adding markdown tables, mermaid graphs, and publishing to Github Pages, --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 73 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 82bfb52d..1aaf1ca4 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ This repo contains the technical reference manual for the Bonsai visual programming language, in addition to articles and examples that document the collective knowledge of the Bonsai user community. > [!NOTE] -> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo. For instance, https://github.com/bonsai-rx/machinelearning hosts the documentation for the Bonsai Machine Learning package. The instructions below apply to both documentation for the base Bonsai library as well as new packages. +> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. The instructions below apply to both documentation for the base Bonsai library as well as new packages. Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using a Github Actions workflow on Github Pages. @@ -15,10 +15,14 @@ Documentation is built using DocFx, a static site generator that automatically g These instructions apply to repos that already have a DocFx website created. -1. Fork the "main" branch of the repository you want to contribute documentation to. +1. Fork the `main` branch of the repository you want to contribute documentation to. 2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.75.3). 3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you make changes. -4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork of the repo and create a pull request to merge that branch with the "main" branch of the original repo. + +> [!NOTE] +> Occasionally, we run into weird bugs and errors with the local preview. Check if the error persists by publishing your fork online. + +4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the "main" branch of the original repo. 5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with "main" will be approved and the contribution will be published. @@ -33,11 +37,12 @@ dotnet new tool-manifest dotnet tool install --local docfx --version 2.75.3 ``` -2) Create a new “docs” folder to host the documentation files. Navigate to folder and initialise a new DocFx website with the following command. +2) Create a new `docs` folder to host the documentation files. Navigate to folder and initialise a new DocFx website with the following command. ```powershell dotnet docfx init ``` + 3) Select these options for the new website ```powershell Name (mysite): Bonsai - Package Name @@ -150,21 +155,17 @@ git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai -# Editing Articles - +# Creating and Editing Articles ## Contributor Style Guide - ### Re-use/update existing documentation When working on an article, first check [the old documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic. -### Including figures +### Table of contents -To include a figure or image in an article: - - save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg` - - add the figure/image to the **images** folder in the repo +* Introduction/Overview/Landing page - the first page of the docs website will be the index.md file that is located in the docs folder. This typically includes a description of what the package does, installation instructions (if its not too complicated) and acknowledgements. To make this page be the first page that is loaded on the docs website, in the articles/toc.yml file, the introduction page should be listed as shown. ### Standard formatting for operators and operator properties @@ -206,3 +207,64 @@ Assuming you want to include `acquisition-example.bonsai`: ```markdown [![Example Workflow](~/images/acquisition-example.svg)](~/workflows/acquisition-example.bonsai) ``` + + + +### Other media + +#### Figures + +> [!NOTE] +> In general, we want to avoid images/screenshots when possible as they do not display well across light/dark themes and are not responsive across different display sizes and resolutions. The following sections detail alternative methods for creating different media types. + +To include a figure or image in an article: + - save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg` + - add the figure/image to the **images** folder in the repo + - reference the figure by + +#### Diagrams and Charts + +DocFX support the creation of flow charts and other diagrams using [Mermaid](https://mermaid.js.org/) syntax which may be helpful for visualising pipelines. + +**Example:** + +```mermaid + +flowchart LR + + A(["Create Python Runtime"]) + B(["Load LDS Module"]) + C(["Create KF Model"]) + D(["Generate Observations"]) + E(["Perform Inference"]) + + A --> B + B --> C + C --> D + D --> E + +``` + +#### Property Tables + +Property grids can be represented as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables) + +**Example:** + +| Category | Property Name | Value | Description +| ---------------- | ------------------- | ---------------------- | -------------------- | +| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train. | +| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | + +# Publishing to Github Pages + +Although this step is not necessary, it can be helpful if you want to check how your edits look online (and if the local preview is not working for some reason). + +1) Setup a new branch called `gh-pages` on your fork of the repository. +2) Go to your repo settings -> `Pages` -> `Build and deployment` - under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. +3) Commit your edits and push to the `main` branch of your repo fork. +4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button. This will build the docs site on the `gh-pages` branch. +5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. +7) The URL for the site can be found in your `Pages` section of your repo settings. + + From 092f1e084b466d741ccc27d734b5b8d696daf6c7 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 28 Mar 2024 12:35:04 -0700 Subject: [PATCH 06/35] added section on testing unpublished packages and other edits to contents --- README.md | 114 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 77 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 1aaf1ca4..fbfe7da1 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ This repo contains the technical reference manual for the Bonsai visual programm > [!NOTE] > This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. The instructions below apply to both documentation for the base Bonsai library as well as new packages. -Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using a Github Actions workflow on Github Pages. +Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects and deployed using a Github Actions workflow on Github Pages. # Would you like to contribute to documentation? @@ -20,7 +20,7 @@ These instructions apply to repos that already have a DocFx website created. 3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you make changes. > [!NOTE] -> Occasionally, we run into weird bugs and errors with the local preview. Check if the error persists by publishing your fork online. +> Occasionally, we run into weird bugs with the local preview. Check if the error persists by publishing your fork online. 4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the "main" branch of the original repo. 5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with "main" will be approved and the contribution will be published. @@ -147,21 +147,28 @@ If one already exists, make sure that it is updated to the latest version and ch * amend main.js to change the github link to the current repository. ``` -8) Add the docfx-tools submodule. This submodule contains scripts for automating SVG export from sample workflows and patches the DocFx CSS templates to add workflow containers. +8) Add the [docfx-tools]() submodule. This submodule contains scripts for automating SVG export from sample workflows and patches the DocFx CSS templates to add workflow containers. ``` git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai ``` +# Testing Unpublished Packages +To write documentation for new packages or releases that have not been published to the community, you can test them in Visual Studio. +(adapted from https://bonsai-rx.org/docs/articles/create-package.html) +1) Install Visual Studio (the community edition can be installed for free) +2) Install Bonsai VS Extensions +3) In Visual Studio, open `src/PackageName.sln` in the repo +4) Press F5 to open the Bonsai editor with the new package added. +5) From here, you can make Bonsai workflows and save them as per normal. # Creating and Editing Articles ## Contributor Style Guide -### Re-use/update existing documentation - -When working on an article, first check [the old documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic. +> [!NOTE] +> When working on an article, first check [the old documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic. ### Table of contents @@ -169,13 +176,11 @@ When working on an article, first check [the old documentation](https://bonsai-r ### Standard formatting for operators and operator properties -When referring to operators (also known as nodes in Bonsai), place operator names inside a pair of backticks and double stars (``**`Operator_name`**``) so that the node names render as bold text in code snippet formatting (i.e. **`CameraCapture`**). - -When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). +When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` 'Operator_name' ``) so that the node names render as in code snippet formatting (i.e. ``CameraCapture``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). -For both operators and operator properties, link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). +When referring to operator properties, simply place the operator property name inside a pair of backticks (`` 'Operator_property_name' ``). -For example, the **`DigitalOutput`** node is part of the `Bonsai.Arduino` namespace/package, and contains a property called `PortName`. To reference this specific property you need to specify the full path to it including namespace, operator name and property name, like so: `xref:Bonsai.Arduino.DigitalOutput.PortName`. +For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package, and contains a property called `PortName`. To reference this specific property you need to specify the full path to it including namespace, operator name and property name, like so: `xref:Bonsai.Arduino.DigitalOutput.PortName`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. The xref will be the namespace + operator name + (optionally) property name. @@ -186,48 +191,56 @@ To find out the full path for any node, right-click on the operator of interest ![Control an LED](~/images/acquisition-led.svg) -- Insert a [**`Boolean`**](xref:Bonsai.Expressions.BooleanProperty) source. -- Insert a [**`DigitalOutput`**](xref:Bonsai.Arduino.DigitalOutput) sink. -- Set the [`Pin`](xref:Bonsai.Arduino.DigitalOutput.Pin) property of the [**`DigitalOutput`**](xref:Bonsai.Arduino.DigitalOutput) operator to 13. -- Configure the [`PortName`](xref:Bonsai.Arduino.DigitalOutput.PortName) property. -- Run the workflow and change the [`Value`](xref:Bonsai.Expressions.BooleanProperty.Value) property of the [**`Boolean`**](xref:Bonsai.Expressions.BooleanProperty) operator. -- **Optional:** Use your mouse to control the LED! Replace the [**`Boolean`**](xref:Bonsai.Expressions.BooleanProperty) operator by a `MouseMove` source (hint: use `GreaterThan`, `LessThan`, or equivalent operators to connect one of the mouse axis to [**`DigitalOutput`**](xref:Bonsai.Arduino.DigitalOutput). +- Insert a [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) source. +- Insert a [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) sink. +- Set the `Pin` property of the [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) operator to 13. +- Configure the `PortName` property. +- Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator. +- **Optional:** Use your mouse to control the LED! Replace the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator by a `MouseMove` source (hint: use `GreaterThan`, `LessThan`, or equivalent operators to connect one of the mouse axis to [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput). ``` -### How to include and/or reference examples of workflows +### Bonsai Workflows -To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor. Then open File -> Export -> Image or use keyboard shortcut Ctrl + Shift + E. Name the example according to the following pattern: `articleFileName_workflowName`. This will export the example workflow as both a `.svg` file and a `.bonsai` file. - -Add the `.svg` file to the **images** folder in this repo, and add the `.bonsai` file to the **workflows** folder in this repo. In the text of the article that includes/references this example workflow, add the `.svg` file as an image and link that image to the `.bonsai` file. +To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName_workflowName`. +Add the `.bonsai` file to the **workflows** folder in the repo. In the text of the article that includes/references this example workflow, add a workflow container. **Example:** -Assuming you want to include `acquisition-example.bonsai`: +Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: ```markdown -[![Example Workflow](~/images/acquisition-example.svg)](~/workflows/acquisition-example.bonsai) +:::workflow +![Send Custom Waveform](../workflows/custom-pulse-train_send-custom-waveform.bonsai) +::: ``` +### Figures +> [!NOTE] +> In general, we want to avoid images/screenshots when possible as they do not display well across light/dark themes and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. -### Other media +To include a figure or image in an article: + - Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. + - Add the figure/image to the **images** folder in the repo. + - Reference the figure in the article with the following code. + - For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a custom attribute on the img element directly like follows. -#### Figures +**Example:** -> [!NOTE] -> In general, we want to avoid images/screenshots when possible as they do not display well across light/dark themes and are not responsive across different display sizes and resolutions. The following sections detail alternative methods for creating different media types. +```markdown +!['Editor Gallery'](~/images/editor-gallery.png){width=500} +``` -To include a figure or image in an article: - - save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg` - - add the figure/image to the **images** folder in the repo - - reference the figure by +!['Editor Gallery'](~/images/editor-gallery.png){width=500} -#### Diagrams and Charts + +### Diagrams and Charts DocFX support the creation of flow charts and other diagrams using [Mermaid](https://mermaid.js.org/) syntax which may be helpful for visualising pipelines. **Example:** +```markdown ```mermaid flowchart LR @@ -244,17 +257,46 @@ flowchart LR D --> E ``` +``` -#### Property Tables +```mermaid -Property grids can be represented as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables) +flowchart LR + + A(["Create Python Runtime"]) + B(["Load LDS Module"]) + C(["Create KF Model"]) + D(["Generate Observations"]) + E(["Perform Inference"]) + + A --> B + B --> C + C --> D + D --> E + +``` + +### Property Tables + +If you want to highlight certain properties to change for a particular application, they can be represented as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). **Example:** +``` markdown | Category | Property Name | Value | Description | ---------------- | ------------------- | ---------------------- | -------------------- | | Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train. | | Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | +``` + +| Category | Property Name | Value | Description +| ---------------- | ------------------- | ---------------------- | -------------------- | +| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train. | +| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | + +### Final Polishing Steps + +Delete redundant blank rows in between markdown lines and at the end of the articles. This improves code readability for future contributors. # Publishing to Github Pages @@ -265,6 +307,4 @@ Although this step is not necessary, it can be helpful if you want to check how 3) Commit your edits and push to the `main` branch of your repo fork. 4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button. This will build the docs site on the `gh-pages` branch. 5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. -7) The URL for the site can be found in your `Pages` section of your repo settings. - - +7) The URL for the site can be found in your `Pages` section of your repo settings. \ No newline at end of file From 5bd73f6bbc515fcea58de34a977e8107a8f6f8a7 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 28 Mar 2024 12:55:14 -0700 Subject: [PATCH 07/35] minor formatting edits to fix examples not showing --- README.md | 36 ++++++++++++++++-------------------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index fbfe7da1..bb50d9cd 100644 --- a/README.md +++ b/README.md @@ -176,13 +176,9 @@ To write documentation for new packages or releases that have not been published ### Standard formatting for operators and operator properties -When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` 'Operator_name' ``) so that the node names render as in code snippet formatting (i.e. ``CameraCapture``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). +When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. -When referring to operator properties, simply place the operator property name inside a pair of backticks (`` 'Operator_property_name' ``). - -For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package, and contains a property called `PortName`. To reference this specific property you need to specify the full path to it including namespace, operator name and property name, like so: `xref:Bonsai.Arduino.DigitalOutput.PortName`. - -To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. The xref will be the namespace + operator name + (optionally) property name. +When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). **Example:** @@ -196,7 +192,7 @@ To find out the full path for any node, right-click on the operator of interest - Set the `Pin` property of the [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) operator to 13. - Configure the `PortName` property. - Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator. -- **Optional:** Use your mouse to control the LED! Replace the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator by a `MouseMove` source (hint: use `GreaterThan`, `LessThan`, or equivalent operators to connect one of the mouse axis to [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput). +- **Optional:** Use your mouse to control the LED! Replace the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator by a `MouseMove` source (hint: use `GreaterThan`, `LessThan`, or equivalent operators to connect one of the mouse axis to [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput)). ``` ### Bonsai Workflows @@ -223,7 +219,7 @@ To include a figure or image in an article: - Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. - Add the figure/image to the **images** folder in the repo. - Reference the figure in the article with the following code. - - For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a custom attribute on the img element directly like follows. + - (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. **Example:** @@ -231,7 +227,7 @@ To include a figure or image in an article: !['Editor Gallery'](~/images/editor-gallery.png){width=500} ``` -!['Editor Gallery'](~/images/editor-gallery.png){width=500} +!['Editor Gallery'](~/articles/images/editor-gallery.png){width=500} ### Diagrams and Charts @@ -240,7 +236,7 @@ DocFX support the creation of flow charts and other diagrams using [Mermaid](htt **Example:** -```markdown +````markdown ```mermaid flowchart LR @@ -257,7 +253,7 @@ flowchart LR D --> E ``` -``` +```` ```mermaid @@ -281,18 +277,18 @@ flowchart LR If you want to highlight certain properties to change for a particular application, they can be represented as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). **Example:** - +Markdown ``` markdown -| Category | Property Name | Value | Description -| ---------------- | ------------------- | ---------------------- | -------------------- | -| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train. | -| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | +| Category | Property Name | Value | Description | +| ---------------- | ------------------- | ---------------------- | ---------------------------------- | +| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| +| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | ``` -| Category | Property Name | Value | Description -| ---------------- | ------------------- | ---------------------- | -------------------- | -| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train. | -| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | +| Category | Property Name | Value | Description | +| ---------------- | ------------------- | ---------------------- | ---------------------------------- | +| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| +| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | ### Final Polishing Steps From 2521838b9085213abf6fa3e80f241422c1e7d95e Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 28 Mar 2024 21:46:02 -0700 Subject: [PATCH 08/35] added docs and TOC organization section, alerts section --- README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 90 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index bb50d9cd..a3b137d1 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ This repo contains the technical reference manual for the Bonsai visual programm > [!NOTE] > This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. The instructions below apply to both documentation for the base Bonsai library as well as new packages. -Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects and deployed using a Github Actions workflow on Github Pages. +Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages. # Would you like to contribute to documentation? @@ -20,7 +20,7 @@ These instructions apply to repos that already have a DocFx website created. 3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you make changes. > [!NOTE] -> Occasionally, we run into weird bugs with the local preview. Check if the error persists by publishing your fork online. +> Occasionally, we run into weird bugs with the local preview. Check if the error persists by [publishing your fork online](#publishing-to-github-pages) 4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the "main" branch of the original repo. 5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with "main" will be approved and the contribution will be published. @@ -54,7 +54,7 @@ Enable PDF? [y/n] (y): n ``` This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. From here on out we just need to make a few tweaks to docfx.json as well as copy over some additional files and folders. -4) Configuring docfx.json - most of the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). A few of the important changes are explained here (not exhaustive). +4) Configure docfx.json - most of the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). ```yml "metadata": [ @@ -147,17 +147,23 @@ If one already exists, make sure that it is updated to the latest version and ch * amend main.js to change the github link to the current repository. ``` -8) Add the [docfx-tools]() submodule. This submodule contains scripts for automating SVG export from sample workflows and patches the DocFx CSS templates to add workflow containers. -``` +8) Add the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. This submodule contains scripts for automating SVG export from sample workflows and patches the DocFx CSS templates to add workflow containers. +```powershell git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai ``` +If the submodule does not show up in your local copy, run these additional commands. + +```powershell +git submodule init +git submodule update +``` # Testing Unpublished Packages To write documentation for new packages or releases that have not been published to the community, you can test them in Visual Studio. (adapted from https://bonsai-rx.org/docs/articles/create-package.html) -1) Install Visual Studio (the community edition can be installed for free) -2) Install Bonsai VS Extensions +1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free) +2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. 3) In Visual Studio, open `src/PackageName.sln` in the repo 4) Press F5 to open the Bonsai editor with the new package added. 5) From here, you can make Bonsai workflows and save them as per normal. @@ -165,14 +171,69 @@ To write documentation for new packages or releases that have not been published # Creating and Editing Articles +## Docs organization + +### Navigation menu +The navigation menu at the top of the DocFX website should have 2-3 links to the main pages of the website. + +* Manual - hosts documentation that explains the basic functions of the various operators in the package. +* API - generated automatically by DocFX from XML comments in the Bonsai package source code. +* Tutorials - optional page that would have examples or tutorials for various applications. + +To construct the navigation menu, edit the docs/toc.yml file to reflect the location and name of the various pages. + +```yml +- name: Manual + href: articles/ +- name: Reference + href: api/ +- name: Tutorials + href: articles/tutorials/ +``` + +### Table of contents +Getting started/Landing page - the first page of the docs website will be an index.md file that is located in the docs folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the articles/toc.yml file, the getting started page should be listed as shown. + +```yml +- href: ../index.md +``` + +> [!NOTE] +> Article names can be ommited as they will be taken from the first `Heading 1` element in the article. + +For the rest of the articles, they can be added to the articles folder and referred to as follows. +Article filenames should be simple and reflect either the article title or operator name (if the article is about a specific operator). + +```yml +- href: ../index.md +- href: lds-overview.md +``` + +To organise articles into different sections, simply include a name before the links to the articles that you want to group together. + +```yml +- href: ../index.md +- name: LinearDynamicalSystems +- href: lds-overview.md +- href: lds-installation-guide-windows.md +- href: lds-installation-guide-linux.md +``` + +This leads to an expanded table of contents. We prefer this approach to other methods that create collapsible, nested table of contents. + +## API docs + + ## Contributor Style Guide > [!NOTE] -> When working on an article, first check [the old documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic. +> When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic that could possibly be used as a reference. -### Table of contents +With DocFX, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine that supports additional markdown extensions. When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: -* Introduction/Overview/Landing page - the first page of the docs website will be the index.md file that is located in the docs folder. This typically includes a description of what the package does, installation instructions (if its not too complicated) and acknowledgements. To make this page be the first page that is loaded on the docs website, in the articles/toc.yml file, the introduction page should be listed as shown. +- Keep article and section titles short and succint so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) +- Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. +- Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". ### Standard formatting for operators and operator properties @@ -227,12 +288,9 @@ To include a figure or image in an article: !['Editor Gallery'](~/images/editor-gallery.png){width=500} ``` -!['Editor Gallery'](~/articles/images/editor-gallery.png){width=500} - - ### Diagrams and Charts -DocFX support the creation of flow charts and other diagrams using [Mermaid](https://mermaid.js.org/) syntax which may be helpful for visualising pipelines. +DocFX supports the creation of flow charts and other diagrams using [Mermaid](https://mermaid.js.org/) syntax which we recommend using to visualize pipelines or other concepts. **Example:** @@ -290,6 +348,24 @@ Markdown | Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| | Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | +### Alerts + +Docfx supports the use of alerts which are block quotes that render in different colors. In general, we recommend only the use of these two alerts as their light and dark mode colors do not conflict with the formatting for property names. + +**Example:** +```markdown +> [!NOTE] +> Information the user should notice even if skimming. + +> [!WARNING] +> Dangerous certain consequences of an action. +``` +> [!NOTE] +> Information the user should notice even if skimming. + +> [!WARNING] +> Dangerous certain consequences of an action. + ### Final Polishing Steps Delete redundant blank rows in between markdown lines and at the end of the articles. This improves code readability for future contributors. From 6ffb7ef27831d8516d0e29bd16ab5f0ca94df73b Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 29 Mar 2024 00:12:28 -0700 Subject: [PATCH 09/35] added individual operator articles (apidoc) --- README.md | 50 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a3b137d1..48a8d9a1 100644 --- a/README.md +++ b/README.md @@ -169,18 +169,18 @@ To write documentation for new packages or releases that have not been published 5) From here, you can make Bonsai workflows and save them as per normal. -# Creating and Editing Articles +# Creating and Editing Documentation -## Docs organization +## Docs Organization -### Navigation menu -The navigation menu at the top of the DocFX website should have 2-3 links to the main pages of the website. +### Navigation bar +The navigation var at the top of the DocFX website should have 2-3 links to the main pages of the website. * Manual - hosts documentation that explains the basic functions of the various operators in the package. * API - generated automatically by DocFX from XML comments in the Bonsai package source code. * Tutorials - optional page that would have examples or tutorials for various applications. -To construct the navigation menu, edit the docs/toc.yml file to reflect the location and name of the various pages. +To construct the navigation bar, edit the docs/toc.yml file to reflect the location and name of the various pages. ```yml - name: Manual @@ -192,14 +192,16 @@ To construct the navigation menu, edit the docs/toc.yml file to reflect the loca ``` ### Table of contents -Getting started/Landing page - the first page of the docs website will be an index.md file that is located in the docs folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the articles/toc.yml file, the getting started page should be listed as shown. +For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a toc.yml file located in the respective folders. The table of contents for the API page is generated automatically. + +Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omited from the tutorials `toc.yml`. ```yml - href: ../index.md ``` > [!NOTE] -> Article names can be ommited as they will be taken from the first `Heading 1` element in the article. +> Article names can be omitted as they will be taken from the first `Heading 1` element in the article. For the rest of the articles, they can be added to the articles folder and referred to as follows. Article filenames should be simple and reflect either the article title or operator name (if the article is about a specific operator). @@ -218,10 +220,35 @@ To organise articles into different sections, simply include a name before the l - href: lds-installation-guide-windows.md - href: lds-installation-guide-linux.md ``` +> [!NOTE] +> While there is another method of grouping articles together that makes a nested table of contents, we prefer this method as it expands the table of contents so that users can see all the articles at once and get to them quicker. + + +### Individual Bonsai operator articles +Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to automatically generated API docs and show up in the Bonsai editor when users right click on individual operators to `View Help`. + +For example, to create documentation for a `PredictPoses` operator that will be included in a `Network Inference` article for the `Bonsai.Sleap` package: + +1) Create a `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. In the markdown file, assign a UID that follows the namespace.operator format. + +```yml +--- +uid: Bonsai.Sleap.PredictPoses +--- + +Write content here. +``` + +2) Create a `Network-Inference.md` article and place it in the `docs\articles` folder. In the markdown file, include a reference to the individual operator.md file. + +```yml + +[!include[Title](~/apidoc/Bonsai_Sleap_PredictPoses.md)] -This leads to an expanded table of contents. We prefer this approach to other methods that create collapsible, nested table of contents. +``` +> [!NOTE] +> The title is optional -## API docs ## Contributor Style Guide @@ -231,7 +258,7 @@ This leads to an expanded table of contents. We prefer this approach to other me With DocFX, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine that supports additional markdown extensions. When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: -- Keep article and section titles short and succint so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) +- Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) - Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. - Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". @@ -256,7 +283,7 @@ When referring to operator properties, simply place the operator property name i - **Optional:** Use your mouse to control the LED! Replace the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator by a `MouseMove` source (hint: use `GreaterThan`, `LessThan`, or equivalent operators to connect one of the mouse axis to [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput)). ``` -### Bonsai Workflows +### Bonsai workflows To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName_workflowName`. Add the `.bonsai` file to the **workflows** folder in the repo. In the text of the article that includes/references this example workflow, add a workflow container. @@ -335,7 +362,6 @@ flowchart LR If you want to highlight certain properties to change for a particular application, they can be represented as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). **Example:** -Markdown ``` markdown | Category | Property Name | Value | Description | | ---------------- | ------------------- | ---------------------- | ---------------------------------- | From a0fd3656971ed4b8bfe3b7de55e611e22bed7ddd Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 29 Mar 2024 11:03:39 -0700 Subject: [PATCH 10/35] Expanded docfx.json configuration options, edits to enhance imperative style and grammar --- README.md | 204 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 129 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 48a8d9a1..e7d878b4 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,14 @@ dotnet new tool-manifest dotnet tool install --local docfx --version 2.75.3 ``` -2) Create a new `docs` folder to host the documentation files. Navigate to folder and initialise a new DocFx website with the following command. +2) Create a new `docs` folder to host the documentation files. Navigate to the folder and initialise a new DocFx website with the following command. ```powershell dotnet docfx init ``` -3) Select these options for the new website +3) Select these options for the new website. + ```powershell Name (mysite): Bonsai - Package Name Generate .NET API documentation? [y/n] (y): y @@ -52,10 +53,11 @@ Markdown docs location (docs): articles Enable site search? [y/n] (y): y Enable PDF? [y/n] (y): n ``` -This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. From here on out we just need to make a few tweaks to docfx.json as well as copy over some additional files and folders. +This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. -4) Configure docfx.json - most of the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). +4) Configure docfx.json - the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). +Add the `filter` attribute to filter out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported). ```yml "metadata": [ { @@ -63,21 +65,66 @@ This creates a docfx.json file in the "docs" folder that hosts the configuration } ] ``` - -This uses the filter.yml file to filter out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported). +Exclude the filter.yml from being included in the building of content. ```yml -"resource": { - "files": [ - "logo.svg", - "favicon.ico", - "images/**", - "workflows/**" +"build": { + "content": [ + { + "exclude": [ + "_site/**", + "filter.yml" + ] + } ] } ``` -List any additional files/folders that are to be used in the docs needs to be added here +List any additional files/folders that are to be used in the doc in the resource attribute. + +```yml +"build": { + "resource": { + "files": [ + "logo.svg", + "favicon.ico", + "images/**", + "workflows/**" + ] + } +} +``` + +Add the `overwrite` attribute to enable individual operator articles stored in the `apidocs` folder to be included in articles and API docs. + +```yml +"build": { + "overwrite": [ + { + "files": [ + "apidoc/**.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], +} +``` + +Modify the template attribute to use the modern template and apply custom templates to enable workflow containers. + +```yml +"template": [ + "default", + "modern", + "bonsai/template", + "template" +] +``` + +Change PackageName and github link to the repo being worked on and add footer information to the `globalMetadata` attribute. ```yml "globalMetadata": { @@ -91,63 +138,68 @@ List any additional files/folders that are to be used in the docs needs to be ad } } ``` -Change PackageName and github link to the repo being worked on and add footer information + +Enable additional markdig (the default DocFX markdown processor) extensions. ```yml -"template": [ - "default", - "modern", - "bonsai/template", - "template" -] +"build": { + "markdownEngineProperties": { + "markdigExtensions": [ + "attributes", + "customcontainers" + ] + } +} ``` -This applies CSS patches to enable custom workflow containers + +Add a `xref` attribute to cross reference operators and properties across the different Bonsai docs websites. ```yml -"xref": [ - "https://bonsai-rx.org/docs/xrefmap.yml", - "https://horizongir.github.io/reactive/xrefmap.yml" -] +"build": { + "xref": [ + "https://bonsai-rx.org/docs/xrefmap.yml", + "https://horizongir.github.io/reactive/xrefmap.yml" + ] +} ``` -This allows for cross reference of operators and properties across the different Bonsai docs websites - 5) In the "docs" folder, create these folders. ```markdown -* articles - this will host markdown files for various articles that will go into the "Manual" documentation -* apidoc - this will host markdown files for individual Bonsai operators or properties that will go into the "Reference" documentation. -* images - this will host images for the website. -* workflows - this will host .bonsai files for example workflows. +- articles - this will host markdown files for various articles that will go into the `Manual` documentation. +- apidoc - this will host markdown files for individual Bonsai operators or properties that will go into the "Reference" documentation. +- images - this will host images for the website. +- workflows - this will host .bonsai files for example workflows. ``` -6) Copy over these files from a repo that has been recently updated, and place them in the root folder of the repo. Amend the files as necessary. +6) Copy over these folders/files from a repo that has been recently updated into the root folder of the repo. Amend the files as necessary. ```markdown -* .github folder - this includes a workflows/docs.yml file that is a Github Actions workflow recipe to build the DocFx website. -If one already exists, make sure that it is updated to the latest version and change the package name parameters +- .github folder - this includes a workflows/docs.yml file that is a Github Actions workflow recipe to build the DocFx website. +If one already exists, make sure that it is updated to the latest version and change the package name parameters. -* .bonsai folder -this includes the files necessary to build a Bonsai environment on Github Actions. - * The config.yml file in the .bonsai folder needs to be amended to include any packages that are necessary for running the SVG export for sample Bonsai workflows on Github Actions (see below for more details). - * The new Bonsai package itself does not need to be included. +- .bonsai folder -this includes the files necessary to build a Bonsai environment on Github Actions. + - The config.yml file in the .bonsai folder needs to be amended to include any packages that are necessary for running the SVG export for sample Bonsai workflows on Github Actions (see below for more details). + - The new Bonsai package itself does not need to be included. -* .gitignore file - this needs to be updated to ignore some of the new workflow files (like the .bonsai packages env) +- .gitignore file - this needs to be updated to ignore some of the new workflow files (like the .bonsai packages env). ``` -7) Copy the rest of these folders and files into the "docs" folder +7) Copy over these folders/files from a repo that has been recently updated into the "docs" folder. ```markdown -* docs/filter.yml file - this filters out obsolete operators from being included in API documentation. -* docs/.gitignore file - this filters out the _site folder that is generated during local preview -* docs/favicon.ico and logo.svg - files for site logo and bookmark icon -* docs/workflows/.gitignore file - this ignore bonsai layout files and svg files -* docs/build.ps1 file - this script is used to export images for sample workflows - * amend the line in the file to the new package name and source location. -* docs/template/public folder- this should contain main.css and main.js which are patches for the default template and utilise the docfx-tools submodule. - * amend main.js to change the github link to the current repository. +- docs/filter.yml file - this filters out obsolete operators from being included in API documentation. +- docs/.gitignore file - this filters out the _site folder that is generated during local preview. +- docs/favicon.ico and logo.svg - files for site logo and bookmark icon. +- docs/workflows/.gitignore file - this ignore bonsai layout files and svg files. +- docs/build.ps1 file - this script is used to export images for sample workflows. + - amend the line in the file to the new package name and source location. +- docs/template/public folder- this should contain main.css and main.js which are patches for the default template and utilise the docfx-tools submodule. + - amend main.js to change the github link to the current repository. ``` -8) Add the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. This submodule contains scripts for automating SVG export from sample workflows and patches the DocFx CSS templates to add workflow containers. +8) Add the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. This submodule contains scripts for automating SVG export from Bonsai workflows and patches the DocFx CSS templates to add workflow containers. + ```powershell git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai ``` @@ -159,8 +211,8 @@ git submodule update ``` # Testing Unpublished Packages -To write documentation for new packages or releases that have not been published to the community, you can test them in Visual Studio. -(adapted from https://bonsai-rx.org/docs/articles/create-package.html) +To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. +Adapted from https://bonsai-rx.org/docs/articles/create-package.html. 1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free) 2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. @@ -168,7 +220,6 @@ To write documentation for new packages or releases that have not been published 4) Press F5 to open the Bonsai editor with the new package added. 5) From here, you can make Bonsai workflows and save them as per normal. - # Creating and Editing Documentation ## Docs Organization @@ -194,7 +245,7 @@ To construct the navigation bar, edit the docs/toc.yml file to reflect the locat ### Table of contents For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a toc.yml file located in the respective folders. The table of contents for the API page is generated automatically. -Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omited from the tutorials `toc.yml`. +Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omitted from the tutorials `toc.yml`. ```yml - href: ../index.md @@ -220,12 +271,12 @@ To organise articles into different sections, simply include a name before the l - href: lds-installation-guide-windows.md - href: lds-installation-guide-linux.md ``` + > [!NOTE] > While there is another method of grouping articles together that makes a nested table of contents, we prefer this method as it expands the table of contents so that users can see all the articles at once and get to them quicker. - ### Individual Bonsai operator articles -Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to automatically generated API docs and show up in the Bonsai editor when users right click on individual operators to `View Help`. +Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to the automatically generated API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. For example, to create documentation for a `PredictPoses` operator that will be included in a `Network Inference` article for the `Bonsai.Sleap` package: @@ -242,14 +293,10 @@ Write content here. 2) Create a `Network-Inference.md` article and place it in the `docs\articles` folder. In the markdown file, include a reference to the individual operator.md file. ```yml - [!include[Title](~/apidoc/Bonsai_Sleap_PredictPoses.md)] - ``` > [!NOTE] -> The title is optional - - +> The title is optional. ## Contributor Style Guide @@ -264,7 +311,9 @@ With DocFX, articles are written in [Markdown](https://dotnet.github.io/docfx/do ### Standard formatting for operators and operator properties -When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. +When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). + +For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). @@ -272,15 +321,11 @@ When referring to operator properties, simply place the operator property name i ```markdown ### **Exercise 7:** Control an LED - -![Control an LED](~/images/acquisition-led.svg) - - Insert a [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) source. - Insert a [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) sink. - Set the `Pin` property of the [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) operator to 13. - Configure the `PortName` property. - Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator. -- **Optional:** Use your mouse to control the LED! Replace the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator by a `MouseMove` source (hint: use `GreaterThan`, `LessThan`, or equivalent operators to connect one of the mouse axis to [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput)). ``` ### Bonsai workflows @@ -301,13 +346,14 @@ Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: ### Figures > [!NOTE] -> In general, we want to avoid images/screenshots when possible as they do not display well across light/dark themes and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. +> Avoid images/screenshots when possible as they do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. To include a figure or image in an article: - - Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. - - Add the figure/image to the **images** folder in the repo. - - Reference the figure in the article with the following code. - - (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. + +1) Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. +2) Add the figure/image to the **images** folder in the repo. +3) Reference the figure in the article with the following code. +4) (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. **Example:** @@ -317,7 +363,7 @@ To include a figure or image in an article: ### Diagrams and Charts -DocFX supports the creation of flow charts and other diagrams using [Mermaid](https://mermaid.js.org/) syntax which we recommend using to visualize pipelines or other concepts. +Use [Mermaid](https://mermaid.js.org/) graphs to visualize flowcharts or pipelines. **Example:** @@ -343,7 +389,6 @@ flowchart LR ```mermaid flowchart LR - A(["Create Python Runtime"]) B(["Load LDS Module"]) C(["Create KF Model"]) @@ -354,12 +399,11 @@ flowchart LR B --> C C --> D D --> E - ``` ### Property Tables -If you want to highlight certain properties to change for a particular application, they can be represented as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). +Highlight properties to change for a particular application by representing them as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). **Example:** ``` markdown @@ -374,9 +418,19 @@ If you want to highlight certain properties to change for a particular applicati | Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| | Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | +### Code snippets +Use code blocks to highlight code to run. Enable language specific highlighting by adding a language identifier at the beginning. + +````markdown +```powershell +dotnet new tool-manifest +dotnet tool install --local docfx --version 2.75.3 +``` +```` + ### Alerts -Docfx supports the use of alerts which are block quotes that render in different colors. In general, we recommend only the use of these two alerts as their light and dark mode colors do not conflict with the formatting for property names. +Use alerts to alert users to important information. Only use either the `Note` or `Warning` alerts as they do not conflict with the formatting for property names. **Example:** ```markdown @@ -398,7 +452,7 @@ Delete redundant blank rows in between markdown lines and at the end of the arti # Publishing to Github Pages -Although this step is not necessary, it can be helpful if you want to check how your edits look online (and if the local preview is not working for some reason). +Although this step is not necessary, it can be helpful if you want to check how your edits look online if the local preview is not working. 1) Setup a new branch called `gh-pages` on your fork of the repository. 2) Go to your repo settings -> `Pages` -> `Build and deployment` - under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. From 4825f061c34644ecc86c6bab0650edb6da5abbdc Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 29 Mar 2024 11:36:14 -0700 Subject: [PATCH 11/35] reorganised sections, added instructions on amending config.yml to add missing packages for SVG export --- README.md | 78 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 43 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index e7d878b4..5496572b 100644 --- a/README.md +++ b/README.md @@ -11,13 +11,13 @@ Documentation is built using DocFx, a static site generator that automatically g # Would you like to contribute to documentation? -## Step by step guide to contributing to existing documentation +## Contributing to existing documentation These instructions apply to repos that already have a DocFx website created. 1. Fork the `main` branch of the repository you want to contribute documentation to. 2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.75.3). -3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you make changes. +3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you [make changes](#creating-and-editing-articles). > [!NOTE] > Occasionally, we run into weird bugs with the local preview. Check if the error persists by [publishing your fork online](#publishing-to-github-pages) @@ -26,7 +26,7 @@ These instructions apply to repos that already have a DocFx website created. 5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with "main" will be approved and the contribution will be published. -## Step by step guide to setting up new documentation +## Setting up new documentation For packages without existing documentation, a new DocFx website needs to be initialized. @@ -113,7 +113,7 @@ Add the `overwrite` attribute to enable individual operator articles stored in t } ``` -Modify the template attribute to use the modern template and apply custom templates to enable workflow containers. +Modify the `template` attribute to use the modern template and apply custom templates to enable workflow containers. ```yml "template": [ @@ -163,38 +163,39 @@ Add a `xref` attribute to cross reference operators and properties across the di } ``` -5) In the "docs" folder, create these folders. +5) In the "docs" folder, create these folders to host various contents that will go into the docs. ```markdown -- articles - this will host markdown files for various articles that will go into the `Manual` documentation. -- apidoc - this will host markdown files for individual Bonsai operators or properties that will go into the "Reference" documentation. -- images - this will host images for the website. -- workflows - this will host .bonsai files for example workflows. +- articles - markdown files for various articles that will go into the `Manual`. +- apidoc - markdown files for individual Bonsai operators to be included in articles or `Reference`. +- images - images for the website. +- workflows - .bonsai files for example workflows. ``` 6) Copy over these folders/files from a repo that has been recently updated into the root folder of the repo. Amend the files as necessary. ```markdown -- .github folder - this includes a workflows/docs.yml file that is a Github Actions workflow recipe to build the DocFx website. -If one already exists, make sure that it is updated to the latest version and change the package name parameters. +- .github folder - contains a workflows/docs.yml file that is a Github Actions workflow recipe. + - Make sure that it is updated to the latest version and change the package name parameters. -- .bonsai folder -this includes the files necessary to build a Bonsai environment on Github Actions. - - The config.yml file in the .bonsai folder needs to be amended to include any packages that are necessary for running the SVG export for sample Bonsai workflows on Github Actions (see below for more details). +- .bonsai folder - files necessary to build a Bonsai environment on Github Actions. + - The config.yml file in the .bonsai folder needs to be amended to include any packages + that are necessary for running the SVG export for sample [Bonsai workflows](#bonsai-workflows). - The new Bonsai package itself does not need to be included. -- .gitignore file - this needs to be updated to ignore some of the new workflow files (like the .bonsai packages env). +- .gitignore file - this needs to be updated to ignore workflow files (i.e. .bonsai packages env). ``` 7) Copy over these folders/files from a repo that has been recently updated into the "docs" folder. ```markdown -- docs/filter.yml file - this filters out obsolete operators from being included in API documentation. -- docs/.gitignore file - this filters out the _site folder that is generated during local preview. +- docs/filter.yml file - filters out obsolete operators from being included in API documentation. +- docs/.gitignore file - filters out the _site folder that is generated during local preview. - docs/favicon.ico and logo.svg - files for site logo and bookmark icon. -- docs/workflows/.gitignore file - this ignore bonsai layout files and svg files. -- docs/build.ps1 file - this script is used to export images for sample workflows. +- docs/workflows/.gitignore file - ignores bonsai layout files and svg files. +- docs/build.ps1 file - script used to export images for sample workflows. - amend the line in the file to the new package name and source location. -- docs/template/public folder- this should contain main.css and main.js which are patches for the default template and utilise the docfx-tools submodule. +- docs/template/public folder- contains main.css and main.js which patches in `docfx-tools`(see next). - amend main.js to change the github link to the current repository. ``` @@ -210,25 +211,15 @@ git submodule init git submodule update ``` -# Testing Unpublished Packages -To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. -Adapted from https://bonsai-rx.org/docs/articles/create-package.html. +# Creating and Editing Articles -1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free) -2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. -3) In Visual Studio, open `src/PackageName.sln` in the repo -4) Press F5 to open the Bonsai editor with the new package added. -5) From here, you can make Bonsai workflows and save them as per normal. - -# Creating and Editing Documentation - -## Docs Organization +## Article Organization ### Navigation bar -The navigation var at the top of the DocFX website should have 2-3 links to the main pages of the website. +The navigation bar at the top of the DocFX website should have 2-3 links to the main pages of the website. * Manual - hosts documentation that explains the basic functions of the various operators in the package. -* API - generated automatically by DocFX from XML comments in the Bonsai package source code. +* Reference - generated automatically by DocFX from XML comments in the Bonsai package source code. * Tutorials - optional page that would have examples or tutorials for various applications. To construct the navigation bar, edit the docs/toc.yml file to reflect the location and name of the various pages. @@ -276,7 +267,7 @@ To organise articles into different sections, simply include a name before the l > While there is another method of grouping articles together that makes a nested table of contents, we prefer this method as it expands the table of contents so that users can see all the articles at once and get to them quicker. ### Individual Bonsai operator articles -Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to the automatically generated API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. +Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to the automatically generated `Reference` API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. For example, to create documentation for a `PredictPoses` operator that will be included in a `Network Inference` article for the `Bonsai.Sleap` package: @@ -343,6 +334,13 @@ Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: ::: ``` +Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. +If any of the nodes are greyed out in the SVG images when published, then the `config.yml` file in `.Bonsai` folders needs to be updated. +For instance, if you used a `KeyDown` operator in your sample Bonsai workflow, the `Bonsai.Windows.Input` package needs to be included. + +Navigate to your local Bonsai installation folder, and you will find a `config.yml` that includes the necessary information to copy over to the `config.yml` file in `.bonsai` folder. +Only copy the lines that reference the package. + ### Figures > [!NOTE] @@ -448,7 +446,17 @@ Use alerts to alert users to important information. Only use either the `Note` o ### Final Polishing Steps -Delete redundant blank rows in between markdown lines and at the end of the articles. This improves code readability for future contributors. +Delete redundant blank rows in between lines and at the end of the articles. This improves code readability for future contributors. + +# Testing Unpublished Packages +To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. +Adapted from https://bonsai-rx.org/docs/articles/create-package.html. + +1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free) +2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. +3) In Visual Studio, open `src/PackageName.sln` in the repo +4) Press F5 to open the Bonsai editor with the new package added. +5) From here, you can make Bonsai workflows and save them as per normal. # Publishing to Github Pages From 921ff9e74afdcfbe4029d87958ce27c778705554 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 29 Mar 2024 12:02:45 -0700 Subject: [PATCH 12/35] added tutorial submodule section and other minor formatting/grammar edits --- README.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5496572b..11690ffa 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,8 @@ These instructions apply to repos that already have a DocFx website created. > [!NOTE] > Occasionally, we run into weird bugs with the local preview. Check if the error persists by [publishing your fork online](#publishing-to-github-pages) -4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the "main" branch of the original repo. -5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with "main" will be approved and the contribution will be published. +4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. +5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. ## Setting up new documentation @@ -65,7 +65,7 @@ Add the `filter` attribute to filter out obsolete nodes in the package from the } ] ``` -Exclude the filter.yml from being included in the building of content. +Exclude the `filter.yml` from being included in the building of content. ```yml "build": { @@ -80,7 +80,7 @@ Exclude the filter.yml from being included in the building of content. } ``` -List any additional files/folders that are to be used in the doc in the resource attribute. +List any additional files/folders that are to be used in the doc in the `resource` attribute. ```yml "build": { @@ -195,13 +195,13 @@ Add a `xref` attribute to cross reference operators and properties across the di - docs/workflows/.gitignore file - ignores bonsai layout files and svg files. - docs/build.ps1 file - script used to export images for sample workflows. - amend the line in the file to the new package name and source location. -- docs/template/public folder- contains main.css and main.js which patches in `docfx-tools`(see next). +- docs/template/public folder- contains main.css and main.js which patches in `docfx-tools`. - amend main.js to change the github link to the current repository. ``` 8) Add the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. This submodule contains scripts for automating SVG export from Bonsai workflows and patches the DocFx CSS templates to add workflow containers. -```powershell +```cmd git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai ``` If the submodule does not show up in your local copy, run these additional commands. @@ -289,6 +289,17 @@ Write content here. > [!NOTE] > The title is optional. +### Tutorials/Examples Submodule +For packages with extensive tutorials, a separate repository can be created and imported as a submodule. +This may be especially helpful if they contain multimedia and other large files. +A tutorial submodule can be added with the following command. + +```cmd +git submodule add https://github.com/bonsai-rx/machinelearning-examples +``` +In addition, the `docfx.json` file needs to be modified. +For an example of how to setup a Tutorial submodule, refer to https://github.com/bonsai-rx/machinelearning and its submodule https://github.com/bonsai-rx/machinelearning-examples. + ## Contributor Style Guide > [!NOTE] @@ -335,7 +346,7 @@ Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: ``` Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. -If any of the nodes are greyed out in the SVG images when published, then the `config.yml` file in `.Bonsai` folders needs to be updated. +If any of the nodes are greyed out in the SVG images when published, then the `config.yml` file in the `.Bonsai` folder needs to be updated. For instance, if you used a `KeyDown` operator in your sample Bonsai workflow, the `Bonsai.Windows.Input` package needs to be included. Navigate to your local Bonsai installation folder, and you will find a `config.yml` that includes the necessary information to copy over to the `config.yml` file in `.bonsai` folder. From bed6dfd18400482df29daa5e7e96c3ed5a408731 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 29 Mar 2024 15:55:49 -0700 Subject: [PATCH 13/35] minor formatting and spelling corrections --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 11690ffa..ef6fee6f 100644 --- a/README.md +++ b/README.md @@ -180,7 +180,7 @@ Add a `xref` attribute to cross reference operators and properties across the di - .bonsai folder - files necessary to build a Bonsai environment on Github Actions. - The config.yml file in the .bonsai folder needs to be amended to include any packages - that are necessary for running the SVG export for sample [Bonsai workflows](#bonsai-workflows). + that are necessary for running the SVG export for sample Bonsai workflows (see section below) - The new Bonsai package itself does not need to be included. - .gitignore file - this needs to be updated to ignore workflow files (i.e. .bonsai packages env). @@ -222,7 +222,7 @@ The navigation bar at the top of the DocFX website should have 2-3 links to the * Reference - generated automatically by DocFX from XML comments in the Bonsai package source code. * Tutorials - optional page that would have examples or tutorials for various applications. -To construct the navigation bar, edit the docs/toc.yml file to reflect the location and name of the various pages. +To construct the navigation bar, edit the `docs/toc.yml` file to reflect the location and name of the various pages. ```yml - name: Manual @@ -234,7 +234,7 @@ To construct the navigation bar, edit the docs/toc.yml file to reflect the locat ``` ### Table of contents -For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a toc.yml file located in the respective folders. The table of contents for the API page is generated automatically. +For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a `toc.yml` file located in the respective folders. The table of contents for the API page is generated automatically. Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omitted from the tutorials `toc.yml`. @@ -463,9 +463,9 @@ Delete redundant blank rows in between lines and at the end of the articles. Thi To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. Adapted from https://bonsai-rx.org/docs/articles/create-package.html. -1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free) +1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free). 2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. -3) In Visual Studio, open `src/PackageName.sln` in the repo +3) In Visual Studio, open `src/PackageName.sln` in the repo. 4) Press F5 to open the Bonsai editor with the new package added. 5) From here, you can make Bonsai workflows and save them as per normal. From cd821c49aab15bba743cba194928f0658db1209a Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Sun, 8 Sep 2024 18:16:03 -0700 Subject: [PATCH 14/35] Trim README, move content to new package documentation article --- README.md | 475 +---------------------------- articles/package-documentation.md | 481 ++++++++++++++++++++++++++++++ 2 files changed, 493 insertions(+), 463 deletions(-) create mode 100644 articles/package-documentation.md diff --git a/README.md b/README.md index ef6fee6f..2f051671 100644 --- a/README.md +++ b/README.md @@ -5,477 +5,26 @@ This repo contains the technical reference manual for the Bonsai visual programming language, in addition to articles and examples that document the collective knowledge of the Bonsai user community. > [!NOTE] -> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. The instructions below apply to both documentation for the base Bonsai library as well as new packages. +> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages. -# Would you like to contribute to documentation? - -## Contributing to existing documentation +# Quick start guide for contributing to documentation These instructions apply to repos that already have a DocFx website created. -1. Fork the `main` branch of the repository you want to contribute documentation to. -2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.75.3). -3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you [make changes](#creating-and-editing-articles). - -> [!NOTE] -> Occasionally, we run into weird bugs with the local preview. Check if the error persists by [publishing your fork online](#publishing-to-github-pages) - -4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. -5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. - - -## Setting up new documentation - -For packages without existing documentation, a new DocFx website needs to be initialized. - -1) In Windows Powershell, setup a local installation of DocFx in the repo with the following commands (executed in the root directory of the repo). - +1. Fork the repository you want to contribute documentation to. +2. Ensure that you are working off the `main` branch in your fork by switching to it if necessary. ```powershell -dotnet new tool-manifest -dotnet tool install --local docfx --version 2.75.3 -``` - -2) Create a new `docs` folder to host the documentation files. Navigate to the folder and initialise a new DocFx website with the following command. - -```powershell -dotnet docfx init -``` - -3) Select these options for the new website. - -```powershell -Name (mysite): Bonsai - Package Name -Generate .NET API documentation? [y/n] (y): y -.NET projects location (src): src -Markdown docs location (docs): articles -Enable site search? [y/n] (y): y -Enable PDF? [y/n] (y): n -``` -This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. - -4) Configure docfx.json - the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). - -Add the `filter` attribute to filter out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported). -```yml -"metadata": [ - { - "filter": "filter.yml" - } -] -``` -Exclude the `filter.yml` from being included in the building of content. - -```yml -"build": { - "content": [ - { - "exclude": [ - "_site/**", - "filter.yml" - ] - } - ] -} -``` - -List any additional files/folders that are to be used in the doc in the `resource` attribute. - -```yml -"build": { - "resource": { - "files": [ - "logo.svg", - "favicon.ico", - "images/**", - "workflows/**" - ] - } -} -``` - -Add the `overwrite` attribute to enable individual operator articles stored in the `apidocs` folder to be included in articles and API docs. - -```yml -"build": { - "overwrite": [ - { - "files": [ - "apidoc/**.md" - ], - "exclude": [ - "obj/**", - "_site/**" - ] - } - ], -} -``` - -Modify the `template` attribute to use the modern template and apply custom templates to enable workflow containers. - -```yml -"template": [ - "default", - "modern", - "bonsai/template", - "template" -] -``` - -Change PackageName and github link to the repo being worked on and add footer information to the `globalMetadata` attribute. - -```yml -"globalMetadata": { - "_appName": "Bonsai - PackageName", - "_appTitle": "Bonsai.PackageName", - "_appFooter": "© 2024 Bonsai Foundation CIC and Contributors. Made with docfx", - "_gitContribute": { - "repo": "https://github.com/bonsai-rx/PackageName", - "branch": "main", - "apiSpecFolder": "apidoc" - } -} -``` - -Enable additional markdig (the default DocFX markdown processor) extensions. - -```yml -"build": { - "markdownEngineProperties": { - "markdigExtensions": [ - "attributes", - "customcontainers" - ] - } -} -``` - -Add a `xref` attribute to cross reference operators and properties across the different Bonsai docs websites. - -```yml -"build": { - "xref": [ - "https://bonsai-rx.org/docs/xrefmap.yml", - "https://horizongir.github.io/reactive/xrefmap.yml" - ] -} -``` - -5) In the "docs" folder, create these folders to host various contents that will go into the docs. - -```markdown -- articles - markdown files for various articles that will go into the `Manual`. -- apidoc - markdown files for individual Bonsai operators to be included in articles or `Reference`. -- images - images for the website. -- workflows - .bonsai files for example workflows. -``` - -6) Copy over these folders/files from a repo that has been recently updated into the root folder of the repo. Amend the files as necessary. - -```markdown -- .github folder - contains a workflows/docs.yml file that is a Github Actions workflow recipe. - - Make sure that it is updated to the latest version and change the package name parameters. - -- .bonsai folder - files necessary to build a Bonsai environment on Github Actions. - - The config.yml file in the .bonsai folder needs to be amended to include any packages - that are necessary for running the SVG export for sample Bonsai workflows (see section below) - - The new Bonsai package itself does not need to be included. - -- .gitignore file - this needs to be updated to ignore workflow files (i.e. .bonsai packages env). -``` - -7) Copy over these folders/files from a repo that has been recently updated into the "docs" folder. - -```markdown -- docs/filter.yml file - filters out obsolete operators from being included in API documentation. -- docs/.gitignore file - filters out the _site folder that is generated during local preview. -- docs/favicon.ico and logo.svg - files for site logo and bookmark icon. -- docs/workflows/.gitignore file - ignores bonsai layout files and svg files. -- docs/build.ps1 file - script used to export images for sample workflows. - - amend the line in the file to the new package name and source location. -- docs/template/public folder- contains main.css and main.js which patches in `docfx-tools`. - - amend main.js to change the github link to the current repository. -``` - -8) Add the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. This submodule contains scripts for automating SVG export from Bonsai workflows and patches the DocFx CSS templates to add workflow containers. - -```cmd -git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai -``` -If the submodule does not show up in your local copy, run these additional commands. - -```powershell -git submodule init -git submodule update -``` - -# Creating and Editing Articles - -## Article Organization - -### Navigation bar -The navigation bar at the top of the DocFX website should have 2-3 links to the main pages of the website. - -* Manual - hosts documentation that explains the basic functions of the various operators in the package. -* Reference - generated automatically by DocFX from XML comments in the Bonsai package source code. -* Tutorials - optional page that would have examples or tutorials for various applications. - -To construct the navigation bar, edit the `docs/toc.yml` file to reflect the location and name of the various pages. - -```yml -- name: Manual - href: articles/ -- name: Reference - href: api/ -- name: Tutorials - href: articles/tutorials/ -``` - -### Table of contents -For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a `toc.yml` file located in the respective folders. The table of contents for the API page is generated automatically. - -Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omitted from the tutorials `toc.yml`. - -```yml -- href: ../index.md -``` - -> [!NOTE] -> Article names can be omitted as they will be taken from the first `Heading 1` element in the article. - -For the rest of the articles, they can be added to the articles folder and referred to as follows. -Article filenames should be simple and reflect either the article title or operator name (if the article is about a specific operator). - -```yml -- href: ../index.md -- href: lds-overview.md -``` - -To organise articles into different sections, simply include a name before the links to the articles that you want to group together. - -```yml -- href: ../index.md -- name: LinearDynamicalSystems -- href: lds-overview.md -- href: lds-installation-guide-windows.md -- href: lds-installation-guide-linux.md -``` - -> [!NOTE] -> While there is another method of grouping articles together that makes a nested table of contents, we prefer this method as it expands the table of contents so that users can see all the articles at once and get to them quicker. - -### Individual Bonsai operator articles -Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to the automatically generated `Reference` API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. - -For example, to create documentation for a `PredictPoses` operator that will be included in a `Network Inference` article for the `Bonsai.Sleap` package: - -1) Create a `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. In the markdown file, assign a UID that follows the namespace.operator format. - -```yml ---- -uid: Bonsai.Sleap.PredictPoses ---- - -Write content here. -``` - -2) Create a `Network-Inference.md` article and place it in the `docs\articles` folder. In the markdown file, include a reference to the individual operator.md file. - -```yml -[!include[Title](~/apidoc/Bonsai_Sleap_PredictPoses.md)] -``` -> [!NOTE] -> The title is optional. - -### Tutorials/Examples Submodule -For packages with extensive tutorials, a separate repository can be created and imported as a submodule. -This may be especially helpful if they contain multimedia and other large files. -A tutorial submodule can be added with the following command. - -```cmd -git submodule add https://github.com/bonsai-rx/machinelearning-examples -``` -In addition, the `docfx.json` file needs to be modified. -For an example of how to setup a Tutorial submodule, refer to https://github.com/bonsai-rx/machinelearning and its submodule https://github.com/bonsai-rx/machinelearning-examples. - -## Contributor Style Guide - -> [!NOTE] -> When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic that could possibly be used as a reference. - -With DocFX, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine that supports additional markdown extensions. When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: - -- Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) -- Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. -- Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". - -### Standard formatting for operators and operator properties - -When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). - -For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. - -When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). - -**Example:** - -```markdown -### **Exercise 7:** Control an LED -- Insert a [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) source. -- Insert a [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) sink. -- Set the `Pin` property of the [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) operator to 13. -- Configure the `PortName` property. -- Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator. +git checkout main ``` - -### Bonsai workflows - -To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName_workflowName`. -Add the `.bonsai` file to the **workflows** folder in the repo. In the text of the article that includes/references this example workflow, add a workflow container. - -**Example:** - -Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: - -```markdown -:::workflow -![Send Custom Waveform](../workflows/custom-pulse-train_send-custom-waveform.bonsai) -::: -``` - -Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. -If any of the nodes are greyed out in the SVG images when published, then the `config.yml` file in the `.Bonsai` folder needs to be updated. -For instance, if you used a `KeyDown` operator in your sample Bonsai workflow, the `Bonsai.Windows.Input` package needs to be included. - -Navigate to your local Bonsai installation folder, and you will find a `config.yml` that includes the necessary information to copy over to the `config.yml` file in `.bonsai` folder. -Only copy the lines that reference the package. - -### Figures - -> [!NOTE] -> Avoid images/screenshots when possible as they do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. - -To include a figure or image in an article: - -1) Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. -2) Add the figure/image to the **images** folder in the repo. -3) Reference the figure in the article with the following code. -4) (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. - -**Example:** - -```markdown -!['Editor Gallery'](~/images/editor-gallery.png){width=500} -``` - -### Diagrams and Charts - -Use [Mermaid](https://mermaid.js.org/) graphs to visualize flowcharts or pipelines. - -**Example:** - -````markdown -```mermaid - -flowchart LR - - A(["Create Python Runtime"]) - B(["Load LDS Module"]) - C(["Create KF Model"]) - D(["Generate Observations"]) - E(["Perform Inference"]) - - A --> B - B --> C - C --> D - D --> E - -``` -```` - -```mermaid - -flowchart LR - A(["Create Python Runtime"]) - B(["Load LDS Module"]) - C(["Create KF Model"]) - D(["Generate Observations"]) - E(["Perform Inference"]) - - A --> B - B --> C - C --> D - D --> E -``` - -### Property Tables - -Highlight properties to change for a particular application by representing them as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). - -**Example:** -``` markdown -| Category | Property Name | Value | Description | -| ---------------- | ------------------- | ---------------------- | ---------------------------------- | -| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| -| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | -``` - -| Category | Property Name | Value | Description | -| ---------------- | ------------------- | ---------------------- | ---------------------------------- | -| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| -| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | - -### Code snippets -Use code blocks to highlight code to run. Enable language specific highlighting by adding a language identifier at the beginning. - -````markdown +3. Create a descriptively named branch for each article/issue that you want to work on. ```powershell -dotnet new tool-manifest -dotnet tool install --local docfx --version 2.75.3 -``` -```` - -### Alerts - -Use alerts to alert users to important information. Only use either the `Note` or `Warning` alerts as they do not conflict with the formatting for property names. - -**Example:** -```markdown -> [!NOTE] -> Information the user should notice even if skimming. - -> [!WARNING] -> Dangerous certain consequences of an action. +git checkout -b your-branch-name ``` -> [!NOTE] -> Information the user should notice even if skimming. - -> [!WARNING] -> Dangerous certain consequences of an action. - -### Final Polishing Steps - -Delete redundant blank rows in between lines and at the end of the articles. This improves code readability for future contributors. - -# Testing Unpublished Packages -To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. -Adapted from https://bonsai-rx.org/docs/articles/create-package.html. - -1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free). -2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. -3) In Visual Studio, open `src/PackageName.sln` in the repo. -4) Press F5 to open the Bonsai editor with the new package added. -5) From here, you can make Bonsai workflows and save them as per normal. - -# Publishing to Github Pages - -Although this step is not necessary, it can be helpful if you want to check how your edits look online if the local preview is not working. +4. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html). +5. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes' +6. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. +7. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. -1) Setup a new branch called `gh-pages` on your fork of the repository. -2) Go to your repo settings -> `Pages` -> `Build and deployment` - under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. -3) Commit your edits and push to the `main` branch of your repo fork. -4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button. This will build the docs site on the `gh-pages` branch. -5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. -7) The URL for the site can be found in your `Pages` section of your repo settings. \ No newline at end of file +For a fuller guide on documentation, check out the [package documentation](./articles/package-documentation.md). diff --git a/articles/package-documentation.md b/articles/package-documentation.md new file mode 100644 index 00000000..ef6fee6f --- /dev/null +++ b/articles/package-documentation.md @@ -0,0 +1,481 @@ +# Bonsai Documentation + +[![](https://img.shields.io/github/actions/workflow/status/bonsai-rx/docs/build.yml?branch=main&style=flat-square&label=Deployment%20status)](https://github.com/bonsai-rx/docs/actions/workflows/build.yml) + +This repo contains the technical reference manual for the Bonsai visual programming language, in addition to articles and examples that document the collective knowledge of the Bonsai user community. + +> [!NOTE] +> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. The instructions below apply to both documentation for the base Bonsai library as well as new packages. + +Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages. + +# Would you like to contribute to documentation? + +## Contributing to existing documentation + +These instructions apply to repos that already have a DocFx website created. + +1. Fork the `main` branch of the repository you want to contribute documentation to. +2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.75.3). +3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you [make changes](#creating-and-editing-articles). + +> [!NOTE] +> Occasionally, we run into weird bugs with the local preview. Check if the error persists by [publishing your fork online](#publishing-to-github-pages) + +4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. +5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. + + +## Setting up new documentation + +For packages without existing documentation, a new DocFx website needs to be initialized. + +1) In Windows Powershell, setup a local installation of DocFx in the repo with the following commands (executed in the root directory of the repo). + +```powershell +dotnet new tool-manifest +dotnet tool install --local docfx --version 2.75.3 +``` + +2) Create a new `docs` folder to host the documentation files. Navigate to the folder and initialise a new DocFx website with the following command. + +```powershell +dotnet docfx init +``` + +3) Select these options for the new website. + +```powershell +Name (mysite): Bonsai - Package Name +Generate .NET API documentation? [y/n] (y): y +.NET projects location (src): src +Markdown docs location (docs): articles +Enable site search? [y/n] (y): y +Enable PDF? [y/n] (y): n +``` +This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. + +4) Configure docfx.json - the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). + +Add the `filter` attribute to filter out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported). +```yml +"metadata": [ + { + "filter": "filter.yml" + } +] +``` +Exclude the `filter.yml` from being included in the building of content. + +```yml +"build": { + "content": [ + { + "exclude": [ + "_site/**", + "filter.yml" + ] + } + ] +} +``` + +List any additional files/folders that are to be used in the doc in the `resource` attribute. + +```yml +"build": { + "resource": { + "files": [ + "logo.svg", + "favicon.ico", + "images/**", + "workflows/**" + ] + } +} +``` + +Add the `overwrite` attribute to enable individual operator articles stored in the `apidocs` folder to be included in articles and API docs. + +```yml +"build": { + "overwrite": [ + { + "files": [ + "apidoc/**.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], +} +``` + +Modify the `template` attribute to use the modern template and apply custom templates to enable workflow containers. + +```yml +"template": [ + "default", + "modern", + "bonsai/template", + "template" +] +``` + +Change PackageName and github link to the repo being worked on and add footer information to the `globalMetadata` attribute. + +```yml +"globalMetadata": { + "_appName": "Bonsai - PackageName", + "_appTitle": "Bonsai.PackageName", + "_appFooter": "© 2024 Bonsai Foundation CIC and Contributors. Made with docfx", + "_gitContribute": { + "repo": "https://github.com/bonsai-rx/PackageName", + "branch": "main", + "apiSpecFolder": "apidoc" + } +} +``` + +Enable additional markdig (the default DocFX markdown processor) extensions. + +```yml +"build": { + "markdownEngineProperties": { + "markdigExtensions": [ + "attributes", + "customcontainers" + ] + } +} +``` + +Add a `xref` attribute to cross reference operators and properties across the different Bonsai docs websites. + +```yml +"build": { + "xref": [ + "https://bonsai-rx.org/docs/xrefmap.yml", + "https://horizongir.github.io/reactive/xrefmap.yml" + ] +} +``` + +5) In the "docs" folder, create these folders to host various contents that will go into the docs. + +```markdown +- articles - markdown files for various articles that will go into the `Manual`. +- apidoc - markdown files for individual Bonsai operators to be included in articles or `Reference`. +- images - images for the website. +- workflows - .bonsai files for example workflows. +``` + +6) Copy over these folders/files from a repo that has been recently updated into the root folder of the repo. Amend the files as necessary. + +```markdown +- .github folder - contains a workflows/docs.yml file that is a Github Actions workflow recipe. + - Make sure that it is updated to the latest version and change the package name parameters. + +- .bonsai folder - files necessary to build a Bonsai environment on Github Actions. + - The config.yml file in the .bonsai folder needs to be amended to include any packages + that are necessary for running the SVG export for sample Bonsai workflows (see section below) + - The new Bonsai package itself does not need to be included. + +- .gitignore file - this needs to be updated to ignore workflow files (i.e. .bonsai packages env). +``` + +7) Copy over these folders/files from a repo that has been recently updated into the "docs" folder. + +```markdown +- docs/filter.yml file - filters out obsolete operators from being included in API documentation. +- docs/.gitignore file - filters out the _site folder that is generated during local preview. +- docs/favicon.ico and logo.svg - files for site logo and bookmark icon. +- docs/workflows/.gitignore file - ignores bonsai layout files and svg files. +- docs/build.ps1 file - script used to export images for sample workflows. + - amend the line in the file to the new package name and source location. +- docs/template/public folder- contains main.css and main.js which patches in `docfx-tools`. + - amend main.js to change the github link to the current repository. +``` + +8) Add the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. This submodule contains scripts for automating SVG export from Bonsai workflows and patches the DocFx CSS templates to add workflow containers. + +```cmd +git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai +``` +If the submodule does not show up in your local copy, run these additional commands. + +```powershell +git submodule init +git submodule update +``` + +# Creating and Editing Articles + +## Article Organization + +### Navigation bar +The navigation bar at the top of the DocFX website should have 2-3 links to the main pages of the website. + +* Manual - hosts documentation that explains the basic functions of the various operators in the package. +* Reference - generated automatically by DocFX from XML comments in the Bonsai package source code. +* Tutorials - optional page that would have examples or tutorials for various applications. + +To construct the navigation bar, edit the `docs/toc.yml` file to reflect the location and name of the various pages. + +```yml +- name: Manual + href: articles/ +- name: Reference + href: api/ +- name: Tutorials + href: articles/tutorials/ +``` + +### Table of contents +For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a `toc.yml` file located in the respective folders. The table of contents for the API page is generated automatically. + +Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omitted from the tutorials `toc.yml`. + +```yml +- href: ../index.md +``` + +> [!NOTE] +> Article names can be omitted as they will be taken from the first `Heading 1` element in the article. + +For the rest of the articles, they can be added to the articles folder and referred to as follows. +Article filenames should be simple and reflect either the article title or operator name (if the article is about a specific operator). + +```yml +- href: ../index.md +- href: lds-overview.md +``` + +To organise articles into different sections, simply include a name before the links to the articles that you want to group together. + +```yml +- href: ../index.md +- name: LinearDynamicalSystems +- href: lds-overview.md +- href: lds-installation-guide-windows.md +- href: lds-installation-guide-linux.md +``` + +> [!NOTE] +> While there is another method of grouping articles together that makes a nested table of contents, we prefer this method as it expands the table of contents so that users can see all the articles at once and get to them quicker. + +### Individual Bonsai operator articles +Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to the automatically generated `Reference` API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. + +For example, to create documentation for a `PredictPoses` operator that will be included in a `Network Inference` article for the `Bonsai.Sleap` package: + +1) Create a `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. In the markdown file, assign a UID that follows the namespace.operator format. + +```yml +--- +uid: Bonsai.Sleap.PredictPoses +--- + +Write content here. +``` + +2) Create a `Network-Inference.md` article and place it in the `docs\articles` folder. In the markdown file, include a reference to the individual operator.md file. + +```yml +[!include[Title](~/apidoc/Bonsai_Sleap_PredictPoses.md)] +``` +> [!NOTE] +> The title is optional. + +### Tutorials/Examples Submodule +For packages with extensive tutorials, a separate repository can be created and imported as a submodule. +This may be especially helpful if they contain multimedia and other large files. +A tutorial submodule can be added with the following command. + +```cmd +git submodule add https://github.com/bonsai-rx/machinelearning-examples +``` +In addition, the `docfx.json` file needs to be modified. +For an example of how to setup a Tutorial submodule, refer to https://github.com/bonsai-rx/machinelearning and its submodule https://github.com/bonsai-rx/machinelearning-examples. + +## Contributor Style Guide + +> [!NOTE] +> When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic that could possibly be used as a reference. + +With DocFX, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine that supports additional markdown extensions. When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: + +- Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) +- Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. +- Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". + +### Standard formatting for operators and operator properties + +When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). + +For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. + +When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). + +**Example:** + +```markdown +### **Exercise 7:** Control an LED +- Insert a [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) source. +- Insert a [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) sink. +- Set the `Pin` property of the [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) operator to 13. +- Configure the `PortName` property. +- Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator. +``` + +### Bonsai workflows + +To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName_workflowName`. +Add the `.bonsai` file to the **workflows** folder in the repo. In the text of the article that includes/references this example workflow, add a workflow container. + +**Example:** + +Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: + +```markdown +:::workflow +![Send Custom Waveform](../workflows/custom-pulse-train_send-custom-waveform.bonsai) +::: +``` + +Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. +If any of the nodes are greyed out in the SVG images when published, then the `config.yml` file in the `.Bonsai` folder needs to be updated. +For instance, if you used a `KeyDown` operator in your sample Bonsai workflow, the `Bonsai.Windows.Input` package needs to be included. + +Navigate to your local Bonsai installation folder, and you will find a `config.yml` that includes the necessary information to copy over to the `config.yml` file in `.bonsai` folder. +Only copy the lines that reference the package. + +### Figures + +> [!NOTE] +> Avoid images/screenshots when possible as they do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. + +To include a figure or image in an article: + +1) Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. +2) Add the figure/image to the **images** folder in the repo. +3) Reference the figure in the article with the following code. +4) (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. + +**Example:** + +```markdown +!['Editor Gallery'](~/images/editor-gallery.png){width=500} +``` + +### Diagrams and Charts + +Use [Mermaid](https://mermaid.js.org/) graphs to visualize flowcharts or pipelines. + +**Example:** + +````markdown +```mermaid + +flowchart LR + + A(["Create Python Runtime"]) + B(["Load LDS Module"]) + C(["Create KF Model"]) + D(["Generate Observations"]) + E(["Perform Inference"]) + + A --> B + B --> C + C --> D + D --> E + +``` +```` + +```mermaid + +flowchart LR + A(["Create Python Runtime"]) + B(["Load LDS Module"]) + C(["Create KF Model"]) + D(["Generate Observations"]) + E(["Perform Inference"]) + + A --> B + B --> C + C --> D + D --> E +``` + +### Property Tables + +Highlight properties to change for a particular application by representing them as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). + +**Example:** +``` markdown +| Category | Property Name | Value | Description | +| ---------------- | ------------------- | ---------------------- | ---------------------------------- | +| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| +| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | +``` + +| Category | Property Name | Value | Description | +| ---------------- | ------------------- | ---------------------- | ---------------------------------- | +| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| +| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | + +### Code snippets +Use code blocks to highlight code to run. Enable language specific highlighting by adding a language identifier at the beginning. + +````markdown +```powershell +dotnet new tool-manifest +dotnet tool install --local docfx --version 2.75.3 +``` +```` + +### Alerts + +Use alerts to alert users to important information. Only use either the `Note` or `Warning` alerts as they do not conflict with the formatting for property names. + +**Example:** +```markdown +> [!NOTE] +> Information the user should notice even if skimming. + +> [!WARNING] +> Dangerous certain consequences of an action. +``` +> [!NOTE] +> Information the user should notice even if skimming. + +> [!WARNING] +> Dangerous certain consequences of an action. + +### Final Polishing Steps + +Delete redundant blank rows in between lines and at the end of the articles. This improves code readability for future contributors. + +# Testing Unpublished Packages +To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. +Adapted from https://bonsai-rx.org/docs/articles/create-package.html. + +1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free). +2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. +3) In Visual Studio, open `src/PackageName.sln` in the repo. +4) Press F5 to open the Bonsai editor with the new package added. +5) From here, you can make Bonsai workflows and save them as per normal. + +# Publishing to Github Pages + +Although this step is not necessary, it can be helpful if you want to check how your edits look online if the local preview is not working. + +1) Setup a new branch called `gh-pages` on your fork of the repository. +2) Go to your repo settings -> `Pages` -> `Build and deployment` - under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. +3) Commit your edits and push to the `main` branch of your repo fork. +4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button. This will build the docs site on the `gh-pages` branch. +5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. +7) The URL for the site can be found in your `Pages` section of your repo settings. \ No newline at end of file From 049f3b2ffb95d844e245ff1068c8b8b14b17d11e Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Sun, 8 Sep 2024 18:56:44 -0700 Subject: [PATCH 15/35] Add documentation alert to create package article - and minor edit to README clarity --- README.md | 21 +++++++-------------- articles/create-package.md | 5 +++++ 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 2f051671..35db2acc 100644 --- a/README.md +++ b/README.md @@ -14,17 +14,10 @@ Documentation is built using DocFx, a static site generator that automatically g These instructions apply to repos that already have a DocFx website created. 1. Fork the repository you want to contribute documentation to. -2. Ensure that you are working off the `main` branch in your fork by switching to it if necessary. -```powershell -git checkout main -``` -3. Create a descriptively named branch for each article/issue that you want to work on. -```powershell -git checkout -b your-branch-name -``` -4. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html). -5. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes' -6. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. -7. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. - -For a fuller guide on documentation, check out the [package documentation](./articles/package-documentation.md). +2. Ensure that you are working off the `main` branch in your fork and create a descriptively named branch for each article/issue that you want to work on. +3. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html). +4. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes' +5. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. +6. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. + +For a fuller guide on documentation, check out the [package documentation](./articles/package-documentation.md) article. diff --git a/articles/create-package.md b/articles/create-package.md index 0ed878cc..54c16be7 100644 --- a/articles/create-package.md +++ b/articles/create-package.md @@ -96,6 +96,11 @@ The Bonsai language can be extended with custom packages, which are installed an } ``` +> [!TIP] +> Use [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) to document your code. +> Check out the [package documentation](./package-documentation.md) article for information on how to use [DocFx](https://dotnet.github.io/docfx/index.html) +> to automatically generate documentation for your package online. + ## Publishing a package project 1. Double-click the name of the project in the Visual Studio Solution Explorer to open up the package metadata. From 97a41364d07336e360b109181f2e5cd70a4bad66 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Tue, 10 Sep 2024 10:38:22 -0700 Subject: [PATCH 16/35] Split doc article, update TOC --- README.md | 2 + articles/create-package.md | 2 +- articles/documentation-style-guide.md | 248 +++++++++++++ articles/package-documentation.md | 492 ++++++++------------------ articles/toc.yml | 4 + 5 files changed, 393 insertions(+), 355 deletions(-) create mode 100644 articles/documentation-style-guide.md diff --git a/README.md b/README.md index 35db2acc..77cab8c0 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ This repo contains the technical reference manual for the Bonsai visual programm Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages. +We welcome all contributions! For more information please refer to our [Contribution Guide](https://bonsai-rx.org/contribute/). + # Quick start guide for contributing to documentation These instructions apply to repos that already have a DocFx website created. diff --git a/articles/create-package.md b/articles/create-package.md index 54c16be7..ae0feea4 100644 --- a/articles/create-package.md +++ b/articles/create-package.md @@ -98,7 +98,7 @@ The Bonsai language can be extended with custom packages, which are installed an > [!TIP] > Use [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) to document your code. -> Check out the [package documentation](./package-documentation.md) article for information on how to use [DocFx](https://dotnet.github.io/docfx/index.html) +> Check out the [Documentation with docfx](./package-documentation.md) article for information on how to use [DocFx](https://dotnet.github.io/docfx/index.html) > to automatically generate documentation for your package online. ## Publishing a package project diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md new file mode 100644 index 00000000..dfc833cf --- /dev/null +++ b/articles/documentation-style-guide.md @@ -0,0 +1,248 @@ +# Documentation Style Guide + +## Article Organization + +The navigation bar at the top of the DocFX website should have 2-3 links to the main pages of the website. + +* Manual - hosts documentation that explains the basic functions of the various operators in the package. +* Reference - generated automatically by DocFX from XML comments in the Bonsai package source code. +* Tutorials - optional page that would have examples or tutorials for various applications. + + +To construct the navigation bar, edit the `docs/toc.yml` file to reflect the location and name of the various pages. + +```yml +- name: Manual + href: articles/ +- name: Reference + href: api/ +- name: Tutorials + href: articles/tutorials/ +``` + +### Table of contents +For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a `toc.yml` file located in the respective folders. The table of contents for the API page is generated automatically. + +Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omitted from the tutorials `toc.yml`. + +```yml +- href: ../index.md +``` + +> [!NOTE] +> Article names can be omitted as they will be taken from the first `Heading 1` element in the article. + +For the rest of the articles, they can be added to the articles folder and referred to as follows. +Article filenames should be simple and reflect either the article title or operator name (if the article is about a specific operator). + +```yml +- href: ../index.md +- href: lds-overview.md +``` + +To organise articles into different sections, simply include a name before the links to the articles that you want to group together. + +```yml +- href: ../index.md +- name: LinearDynamicalSystems +- href: lds-overview.md +- href: lds-installation-guide-windows.md +- href: lds-installation-guide-linux.md +``` + +> [!NOTE] +> While there is another method of grouping articles together that makes a nested table of contents, we prefer this method as it expands the table of contents so that users can see all the articles at once and get to them quicker. + +### Individual Bonsai operator articles +Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to the automatically generated `Reference` API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. + +For example, to create documentation for a `PredictPoses` operator that will be included in a `Network Inference` article for the `Bonsai.Sleap` package: + +1) Create a `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. In the markdown file, assign a UID that follows the namespace.operator format. + +```yml +--- +uid: Bonsai.Sleap.PredictPoses +--- + +Write content here. +``` + +2) Create a `Network-Inference.md` article and place it in the `docs\articles` folder. In the markdown file, include a reference to the individual operator.md file. + +```yml +[!include[Title](~/apidoc/Bonsai_Sleap_PredictPoses.md)] +``` +> [!NOTE] +> The title is optional. + +### Tutorials/Examples Submodule +For packages with extensive tutorials, a separate repository can be created and imported as a submodule. +This may be especially helpful if they contain multimedia and other large files. +A tutorial submodule can be added with the following command. + +```cmd +git submodule add https://github.com/bonsai-rx/machinelearning-examples +``` +In addition, the `docfx.json` file needs to be modified. +For an example of how to setup a Tutorial submodule, refer to https://github.com/bonsai-rx/machinelearning and its submodule https://github.com/bonsai-rx/machinelearning-examples. + +## Contributor Style Guide + +> [!NOTE] +> When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic that could possibly be used as a reference. + +With DocFX, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine that supports additional markdown extensions. When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: + +- Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) +- Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. +- Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". + +### Standard formatting for operators and operator properties + +When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). + +For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. + +When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). + +**Example:** + +```markdown +### **Exercise 7:** Control an LED +- Insert a [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) source. +- Insert a [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) sink. +- Set the `Pin` property of the [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) operator to 13. +- Configure the `PortName` property. +- Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator. +``` + +### Bonsai workflows + +To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName_workflowName`. +Add the `.bonsai` file to the **workflows** folder in the repo. In the text of the article that includes/references this example workflow, add a workflow container. + +**Example:** + +Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: + +```markdown +:::workflow +![Send Custom Waveform](../workflows/custom-pulse-train_send-custom-waveform.bonsai) +::: +``` + +Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. +If any of the nodes are greyed out in the SVG images when published, then the `config.yml` file in the `.Bonsai` folder needs to be updated. +For instance, if you used a `KeyDown` operator in your sample Bonsai workflow, the `Bonsai.Windows.Input` package needs to be included. + +Navigate to your local Bonsai installation folder, and you will find a `config.yml` that includes the necessary information to copy over to the `config.yml` file in `.bonsai` folder. +Only copy the lines that reference the package. + +### Figures + +> [!NOTE] +> Avoid images/screenshots when possible as they do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. + +To include a figure or image in an article: + +1) Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. +2) Add the figure/image to the **images** folder in the repo. +3) Reference the figure in the article with the following code. +4) (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. + +**Example:** + +```markdown +!['Editor Gallery'](~/images/editor-gallery.png){width=500} +``` + +### Diagrams and Charts + +Use [Mermaid](https://mermaid.js.org/) graphs to visualize flowcharts or pipelines. + +**Example:** + +````markdown +```mermaid + +flowchart LR + + A(["Create Python Runtime"]) + B(["Load LDS Module"]) + C(["Create KF Model"]) + D(["Generate Observations"]) + E(["Perform Inference"]) + + A --> B + B --> C + C --> D + D --> E + +``` +```` + +```mermaid + +flowchart LR + A(["Create Python Runtime"]) + B(["Load LDS Module"]) + C(["Create KF Model"]) + D(["Generate Observations"]) + E(["Perform Inference"]) + + A --> B + B --> C + C --> D + D --> E +``` + +### Property Tables + +Highlight properties to change for a particular application by representing them as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). + +**Example:** +``` markdown +| Category | Property Name | Value | Description | +| ---------------- | ------------------- | ---------------------- | ---------------------------------- | +| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| +| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | +``` + +| Category | Property Name | Value | Description | +| ---------------- | ------------------- | ---------------------- | ---------------------------------- | +| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| +| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | + +### Code snippets +Use code blocks to highlight code to run. Enable language specific highlighting by adding a language identifier at the beginning. + +````markdown +```powershell +dotnet new tool-manifest +dotnet tool install --local docfx --version 2.75.3 +``` +```` + +### Alerts + +Use alerts to alert users to important information. Only use either the `Note` or `Warning` alerts as they do not conflict with the formatting for property names. + +**Example:** +```markdown +> [!NOTE] +> Information the user should notice even if skimming. + +> [!WARNING] +> Dangerous certain consequences of an action. +``` +> [!NOTE] +> Information the user should notice even if skimming. + +> [!WARNING] +> Dangerous certain consequences of an action. + +### Final Polishing Steps + +Delete redundant blank rows in between lines and at the end of the articles. This improves code readability for future contributors. + diff --git a/articles/package-documentation.md b/articles/package-documentation.md index ef6fee6f..10e85e9b 100644 --- a/articles/package-documentation.md +++ b/articles/package-documentation.md @@ -1,43 +1,45 @@ -# Bonsai Documentation +# Documentation With Docfx +Effective documentation plays a crucial role in driving the adoption and usage of custom packages. Clear, well-organized documentation helps users understand package functionality, integrate it into their workflows, and troubleshoot issues. -[![](https://img.shields.io/github/actions/workflow/status/bonsai-rx/docs/build.yml?branch=main&style=flat-square&label=Deployment%20status)](https://github.com/bonsai-rx/docs/actions/workflows/build.yml) +For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to support key Bonsai features, we encourage using `docfx` for consistency and support within the Bonsai Ecosystem. The following article will go into how to create a `docfx` website for your package. -This repo contains the technical reference manual for the Bonsai visual programming language, in addition to articles and examples that document the collective knowledge of the Bonsai user community. +> [!TIP] +> We recommend using a code editor with an integrated terminal like [Visual Studio Code](https://code.visualstudio.com/) to follow along with these instructions. -> [!NOTE] -> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. The instructions below apply to both documentation for the base Bonsai library as well as new packages. - -Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages. - -# Would you like to contribute to documentation? - -## Contributing to existing documentation - -These instructions apply to repos that already have a DocFx website created. - -1. Fork the `main` branch of the repository you want to contribute documentation to. -2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.75.3). -3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you [make changes](#creating-and-editing-articles). - -> [!NOTE] -> Occasionally, we run into weird bugs with the local preview. Check if the error persists by [publishing your fork online](#publishing-to-github-pages) +## Repository organization +For effective long term maintenance of documentation across different repos, package repos should be organised according to this standardized folder structure: +``` +. +├── .bonsai # See note below +├── .github/workflows # See note below +│ └── build.yml +├── docs # Folder to setup docfx +└── src + └── Bonsai.PackageName # Project files here +... +``` -4. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. -5. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. +- `.bonsai` - A local Bonsai [environment](https://bonsai-rx.org/docs/articles/environments.html) is required for a script that exports Bonsai workflow images. To create one: +```powershell +dotnet new install Bonsai.Templates +dotnet new bonsaienv +``` -## Setting up new documentation +- `.github/workflows` - The docfx website is published to [Github Pages](https://pages.github.com/) using a [Github Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) recipe named [build.yml](https://github.com/bonsai-rx/docs/blob/main/.github/workflows/build.yml). Download `build.yml` and place it in this folder. -For packages without existing documentation, a new DocFx website needs to be initialized. +Now that your repository is organized, you can move on to setup docfx. -1) In Windows Powershell, setup a local installation of DocFx in the repo with the following commands (executed in the root directory of the repo). +## Setting up docfx +1) Setup a local installation of `docfx` in your package repo with the following commands (executed in the root directory): ```powershell dotnet new tool-manifest -dotnet tool install --local docfx --version 2.75.3 +dotnet tool install --local docfx ``` +This should create a `.config` folder in the root directory that contains `docfx` version info. -2) Create a new `docs` folder to host the documentation files. Navigate to the folder and initialise a new DocFx website with the following command. +2) Navigate to the `docs` folder and initialise a new DocFx website with the following command. ```powershell dotnet docfx init @@ -53,34 +55,72 @@ Markdown docs location (docs): articles Enable site search? [y/n] (y): y Enable PDF? [y/n] (y): n ``` -This creates a docfx.json file in the "docs" folder that hosts the configuration options for the website. -4) Configure docfx.json - the parameters to be changed can be copied over from the docfx.json in a repo that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). +Congrats, you now have a minimal `docfx` website. Run the following command to generate a local preview of the website, and verify that API documentation for your package has been generated successfully: -Add the `filter` attribute to filter out obsolete nodes in the package from the documentation that have been included for compatibility purposes (but are no longer supported). -```yml -"metadata": [ - { - "filter": "filter.yml" - } -] +```powershell +dotnet docfx docfx.json --serve ``` -Exclude the `filter.yml` from being included in the building of content. -```yml -"build": { - "content": [ - { - "exclude": [ - "_site/**", - "filter.yml" - ] - } - ] -} +### Docfx folder organization + +Before proceeding further into customizing the `docfx` website, the `docs` folder should be organised according to this layout for effective long term maintenance. + +``` +. +├── api # Automatically generated by docfx +├── apidoc # Place individual operator articles here (add link) +├── articles # Place "Manual" articles here +├── bonsai # Docfx-tools submodule, see note below +├── images # Place images like screenshots here +├── workflow # Store .bonsai workflow files here +├── favicon.ico # Website bookmark logo +├── logo.svg # Website logo +├── template # See note below +│ └── public +│ ├── main.css +│ └── main.js +├── build.ps1 +└── docfx.json +... +``` + +`bonsai` - this folder is where we place a submodule that we have created called [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from Bonsai workflows and patches the `docfx` CSS templates to add workflow containers. To add it, run: + +```powershell +git submodule add https://github.com/bonsai-rx/docfx-tools bonsai +``` +If the `bonsai` folder doesnt contain any files, run + +```powershell +git submodule update --init +``` + + +6) Copy over these folders/files from a repo that has been recently updated into the root folder of the repo. Amend the files as necessary. + +```markdown +- .gitignore file - this needs to be updated to ignore workflow files (i.e. .bonsai packages env). +``` + +7) Copy over these folders/files from a repo that has been recently updated into the "docs" folder. + +```markdown +- docs/.gitignore file - filters out the _site folder that is generated during local preview. +- docs/workflows/.gitignore file - ignores bonsai layout files and svg files. +- docs/build.ps1 file - script used to export images for sample workflows. + - amend the line in the file to the new package name and source location. +- docs/template/public folder- contains main.css and main.js which patches in `docfx-tools`. + - amend main.js to change the github link to the current repository. ``` -List any additional files/folders that are to be used in the doc in the `resource` attribute. + +### Configuring docfx + +To fully utilize docfx, we have to modify the `docfx.json` file in the `docs` folder, which hosts the configuration options for the website. There are many possible configuration options that can be changed in the `docfx.json`, if in doubt refer to the [docfx documentation](https://dotnet.github.io/docfx/) or a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). + + +1) Add additional files/folders that are to be used in the doc in the `resource` attribute. ```yml "build": { @@ -95,25 +135,7 @@ List any additional files/folders that are to be used in the doc in the `resourc } ``` -Add the `overwrite` attribute to enable individual operator articles stored in the `apidocs` folder to be included in articles and API docs. - -```yml -"build": { - "overwrite": [ - { - "files": [ - "apidoc/**.md" - ], - "exclude": [ - "obj/**", - "_site/**" - ] - } - ], -} -``` - -Modify the `template` attribute to use the modern template and apply custom templates to enable workflow containers. +2) Modify the `template` attribute to use the modern template and apply the `docfx-tools` custom templates to enable workflow containers. ```yml "template": [ @@ -124,7 +146,7 @@ Modify the `template` attribute to use the modern template and apply custom temp ] ``` -Change PackageName and github link to the repo being worked on and add footer information to the `globalMetadata` attribute. +3) Change PackageName and github link to the repo being worked on and add footer information to the `globalMetadata` attribute. ```yml "globalMetadata": { @@ -138,8 +160,7 @@ Change PackageName and github link to the repo being worked on and add footer in } } ``` - -Enable additional markdig (the default DocFX markdown processor) extensions. +4) Enable additional markdig (the default DocFX markdown processor) extensions. ```yml "build": { @@ -152,7 +173,7 @@ Enable additional markdig (the default DocFX markdown processor) extensions. } ``` -Add a `xref` attribute to cross reference operators and properties across the different Bonsai docs websites. +5) Add a `xref` attribute to cross reference operators and properties across the different Bonsai docs websites. ```yml "build": { @@ -163,303 +184,61 @@ Add a `xref` attribute to cross reference operators and properties across the di } ``` -5) In the "docs" folder, create these folders to host various contents that will go into the docs. -```markdown -- articles - markdown files for various articles that will go into the `Manual`. -- apidoc - markdown files for individual Bonsai operators to be included in articles or `Reference`. -- images - images for the website. -- workflows - .bonsai files for example workflows. -``` +Optional: -6) Copy over these folders/files from a repo that has been recently updated into the root folder of the repo. Amend the files as necessary. - -```markdown -- .github folder - contains a workflows/docs.yml file that is a Github Actions workflow recipe. - - Make sure that it is updated to the latest version and change the package name parameters. - -- .bonsai folder - files necessary to build a Bonsai environment on Github Actions. - - The config.yml file in the .bonsai folder needs to be amended to include any packages - that are necessary for running the SVG export for sample Bonsai workflows (see section below) - - The new Bonsai package itself does not need to be included. - -- .gitignore file - this needs to be updated to ignore workflow files (i.e. .bonsai packages env). -``` - -7) Copy over these folders/files from a repo that has been recently updated into the "docs" folder. - -```markdown -- docs/filter.yml file - filters out obsolete operators from being included in API documentation. -- docs/.gitignore file - filters out the _site folder that is generated during local preview. -- docs/favicon.ico and logo.svg - files for site logo and bookmark icon. -- docs/workflows/.gitignore file - ignores bonsai layout files and svg files. -- docs/build.ps1 file - script used to export images for sample workflows. - - amend the line in the file to the new package name and source location. -- docs/template/public folder- contains main.css and main.js which patches in `docfx-tools`. - - amend main.js to change the github link to the current repository. -``` - -8) Add the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. This submodule contains scripts for automating SVG export from Bonsai workflows and patches the DocFx CSS templates to add workflow containers. - -```cmd -git submodule add https://github.com/bonsai-rx/docfx-tools docs/bonsai -``` -If the submodule does not show up in your local copy, run these additional commands. - -```powershell -git submodule init -git submodule update -``` - -# Creating and Editing Articles - -## Article Organization - -### Navigation bar -The navigation bar at the top of the DocFX website should have 2-3 links to the main pages of the website. - -* Manual - hosts documentation that explains the basic functions of the various operators in the package. -* Reference - generated automatically by DocFX from XML comments in the Bonsai package source code. -* Tutorials - optional page that would have examples or tutorials for various applications. - -To construct the navigation bar, edit the `docs/toc.yml` file to reflect the location and name of the various pages. +1) [Filtering Operators](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) - Sometimes in the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. To do so we can add the `filter` attribute to `docfx.json` to filter out nodes in the package. ```yml -- name: Manual - href: articles/ -- name: Reference - href: api/ -- name: Tutorials - href: articles/tutorials/ -``` - -### Table of contents -For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a `toc.yml` file located in the respective folders. The table of contents for the API page is generated automatically. - -Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omitted from the tutorials `toc.yml`. - -```yml -- href: ../index.md +"metadata": [ + { + "filter": "filter.yml" + } +] ``` -> [!NOTE] -> Article names can be omitted as they will be taken from the first `Heading 1` element in the article. - -For the rest of the articles, they can be added to the articles folder and referred to as follows. -Article filenames should be simple and reflect either the article title or operator name (if the article is about a specific operator). +Make a file called `filter.yml` with content such as below and place in the `docs` directory. ```yml -- href: ../index.md -- href: lds-overview.md +apiRules: +- exclude: + hasAttribute: + uid: System.ObsoleteAttribute ``` -To organise articles into different sections, simply include a name before the links to the articles that you want to group together. +Finally, exclude `filter.yml` from being included in the building of content. ```yml -- href: ../index.md -- name: LinearDynamicalSystems -- href: lds-overview.md -- href: lds-installation-guide-windows.md -- href: lds-installation-guide-linux.md -``` - -> [!NOTE] -> While there is another method of grouping articles together that makes a nested table of contents, we prefer this method as it expands the table of contents so that users can see all the articles at once and get to them quicker. - -### Individual Bonsai operator articles -Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to the automatically generated `Reference` API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. - -For example, to create documentation for a `PredictPoses` operator that will be included in a `Network Inference` article for the `Bonsai.Sleap` package: - -1) Create a `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. In the markdown file, assign a UID that follows the namespace.operator format. - -```yml ---- -uid: Bonsai.Sleap.PredictPoses ---- - -Write content here. +"build": { + "content": [ + { + "exclude": [ + "_site/**", + "filter.yml" + ] + } + ] +} ``` -2) Create a `Network-Inference.md` article and place it in the `docs\articles` folder. In the markdown file, include a reference to the individual operator.md file. +Add the `overwrite` attribute to enable individual operator articles stored in the `apidocs` folder to be included in articles and API docs. ```yml -[!include[Title](~/apidoc/Bonsai_Sleap_PredictPoses.md)] -``` -> [!NOTE] -> The title is optional. - -### Tutorials/Examples Submodule -For packages with extensive tutorials, a separate repository can be created and imported as a submodule. -This may be especially helpful if they contain multimedia and other large files. -A tutorial submodule can be added with the following command. - -```cmd -git submodule add https://github.com/bonsai-rx/machinelearning-examples -``` -In addition, the `docfx.json` file needs to be modified. -For an example of how to setup a Tutorial submodule, refer to https://github.com/bonsai-rx/machinelearning and its submodule https://github.com/bonsai-rx/machinelearning-examples. - -## Contributor Style Guide - -> [!NOTE] -> When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic that could possibly be used as a reference. - -With DocFX, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine that supports additional markdown extensions. When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: - -- Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) -- Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. -- Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". - -### Standard formatting for operators and operator properties - -When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). - -For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. - -When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). - -**Example:** - -```markdown -### **Exercise 7:** Control an LED -- Insert a [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) source. -- Insert a [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) sink. -- Set the `Pin` property of the [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) operator to 13. -- Configure the `PortName` property. -- Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator. -``` - -### Bonsai workflows - -To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName_workflowName`. -Add the `.bonsai` file to the **workflows** folder in the repo. In the text of the article that includes/references this example workflow, add a workflow container. - -**Example:** - -Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: - -```markdown -:::workflow -![Send Custom Waveform](../workflows/custom-pulse-train_send-custom-waveform.bonsai) -::: -``` - -Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. -If any of the nodes are greyed out in the SVG images when published, then the `config.yml` file in the `.Bonsai` folder needs to be updated. -For instance, if you used a `KeyDown` operator in your sample Bonsai workflow, the `Bonsai.Windows.Input` package needs to be included. - -Navigate to your local Bonsai installation folder, and you will find a `config.yml` that includes the necessary information to copy over to the `config.yml` file in `.bonsai` folder. -Only copy the lines that reference the package. - -### Figures - -> [!NOTE] -> Avoid images/screenshots when possible as they do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. - -To include a figure or image in an article: - -1) Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. -2) Add the figure/image to the **images** folder in the repo. -3) Reference the figure in the article with the following code. -4) (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. - -**Example:** - -```markdown -!['Editor Gallery'](~/images/editor-gallery.png){width=500} -``` - -### Diagrams and Charts - -Use [Mermaid](https://mermaid.js.org/) graphs to visualize flowcharts or pipelines. - -**Example:** - -````markdown -```mermaid - -flowchart LR - - A(["Create Python Runtime"]) - B(["Load LDS Module"]) - C(["Create KF Model"]) - D(["Generate Observations"]) - E(["Perform Inference"]) - - A --> B - B --> C - C --> D - D --> E - -``` -```` - -```mermaid - -flowchart LR - A(["Create Python Runtime"]) - B(["Load LDS Module"]) - C(["Create KF Model"]) - D(["Generate Observations"]) - E(["Perform Inference"]) - - A --> B - B --> C - C --> D - D --> E -``` - -### Property Tables - -Highlight properties to change for a particular application by representing them as [markdown pipe tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). - -**Example:** -``` markdown -| Category | Property Name | Value | Description | -| ---------------- | ------------------- | ---------------------- | ---------------------------------- | -| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| -| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | -``` - -| Category | Property Name | Value | Description | -| ---------------- | ------------------- | ---------------------- | ---------------------------------- | -| Pulse Timing | `PulseTrainDelay` | 0.0001 - 3600 (secs) | The delay to start the pulse train.| -| Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | - -### Code snippets -Use code blocks to highlight code to run. Enable language specific highlighting by adding a language identifier at the beginning. - -````markdown -```powershell -dotnet new tool-manifest -dotnet tool install --local docfx --version 2.75.3 -``` -```` - -### Alerts - -Use alerts to alert users to important information. Only use either the `Note` or `Warning` alerts as they do not conflict with the formatting for property names. - -**Example:** -```markdown -> [!NOTE] -> Information the user should notice even if skimming. - -> [!WARNING] -> Dangerous certain consequences of an action. +"build": { + "overwrite": [ + { + "files": [ + "apidoc/**.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], +} ``` -> [!NOTE] -> Information the user should notice even if skimming. - -> [!WARNING] -> Dangerous certain consequences of an action. - -### Final Polishing Steps - -Delete redundant blank rows in between lines and at the end of the articles. This improves code readability for future contributors. - -# Testing Unpublished Packages +## Testing Unpublished Packages To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. Adapted from https://bonsai-rx.org/docs/articles/create-package.html. @@ -469,7 +248,7 @@ Adapted from https://bonsai-rx.org/docs/articles/create-package.html. 4) Press F5 to open the Bonsai editor with the new package added. 5) From here, you can make Bonsai workflows and save them as per normal. -# Publishing to Github Pages +## Publishing to Github Pages Although this step is not necessary, it can be helpful if you want to check how your edits look online if the local preview is not working. @@ -478,4 +257,9 @@ Although this step is not necessary, it can be helpful if you want to check how 3) Commit your edits and push to the `main` branch of your repo fork. 4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button. This will build the docs site on the `gh-pages` branch. 5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. -7) The URL for the site can be found in your `Pages` section of your repo settings. \ No newline at end of file +7) The URL for the site can be found in your `Pages` section of your repo settings. + + +## Docfx Troubleshooting +> [!NOTE] +> Occasionally, we run into weird bugs with the local preview. Check if the error persists by [publishing your fork online](#publishing-to-github-pages) \ No newline at end of file diff --git a/articles/toc.yml b/articles/toc.yml index b0601218..eed66458 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -33,6 +33,10 @@ href: scripting-extensions.md - name: Creating a Package href: create-package.md + - name: Documentation With Docfx + href: package-documentation.md + - name: Documentation Style Guide + href: documentation-style-guide.md - name: Design Guidelines href: design-guidelines.md items: From e8cc69ac54f49cc1057ff58a0ab9861017d525c4 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 11 Sep 2024 00:00:28 -0700 Subject: [PATCH 17/35] Clean up docfx article, add directory trees --- README.md | 8 +- articles/create-package.md | 3 +- articles/package-documentation.md | 194 +++++++++++++++++------------- 3 files changed, 116 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index 77cab8c0..2ab8bad9 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,12 @@ These instructions apply to repos that already have a DocFx website created. 1. Fork the repository you want to contribute documentation to. 2. Ensure that you are working off the `main` branch in your fork and create a descriptively named branch for each article/issue that you want to work on. -3. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html). -4. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes' +3. Download and install dotnet (https://dotnet.microsoft.com/en-us/download) +4. Restore the docfx by running +```powershell +dotnet tool restore +``` +4. In a Windows Powershell, use the command `dotnet docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes' 5. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. 6. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. diff --git a/articles/create-package.md b/articles/create-package.md index ae0feea4..bc21cdfc 100644 --- a/articles/create-package.md +++ b/articles/create-package.md @@ -98,8 +98,7 @@ The Bonsai language can be extended with custom packages, which are installed an > [!TIP] > Use [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) to document your code. -> Check out the [Documentation with docfx](./package-documentation.md) article for information on how to use [DocFx](https://dotnet.github.io/docfx/index.html) -> to automatically generate documentation for your package online. +> Check out the [Documentation with docfx](./package-documentation.md) article for information on how to use [DocFx](https://dotnet.github.io/docfx/index.html) to automatically generate documentation for your package online. ## Publishing a package project diff --git a/articles/package-documentation.md b/articles/package-documentation.md index 10e85e9b..d63c7b6b 100644 --- a/articles/package-documentation.md +++ b/articles/package-documentation.md @@ -1,25 +1,27 @@ # Documentation With Docfx Effective documentation plays a crucial role in driving the adoption and usage of custom packages. Clear, well-organized documentation helps users understand package functionality, integrate it into their workflows, and troubleshoot issues. -For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to support key Bonsai features, we encourage using `docfx` for consistency and support within the Bonsai Ecosystem. The following article will go into how to create a `docfx` website for your package. +For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to support key Bonsai features, we encourage using `docfx` for consistency and support within the Bonsai Ecosystem. + +The following article will go into how to create a `docfx` website for your package. For documentation style guidelines, check out the [Documentation Style Guide](./documentation-style-guide.md). > [!TIP] > We recommend using a code editor with an integrated terminal like [Visual Studio Code](https://code.visualstudio.com/) to follow along with these instructions. ## Repository organization -For effective long term maintenance of documentation across different repos, package repos should be organised according to this standardized folder structure: +For effective long term maintenance of documentation across different repositories, package repositories should be organised according to this standardized folder structure before setting up `docfx`: ``` . -├── .bonsai # See note below -├── .github/workflows # See note below +├── .bonsai/ # Local Bonsai Environment (see note below) +├── .github/workflows/ # Github Actions Folder (see note below) │ └── build.yml -├── docs # Folder to setup docfx -└── src - └── Bonsai.PackageName # Project files here +├── docs/ # Folder to setup docfx +└── src/ + └── Bonsai.PackageName/ # Project files here ... ``` -- `.bonsai` - A local Bonsai [environment](https://bonsai-rx.org/docs/articles/environments.html) is required for a script that exports Bonsai workflow images. To create one: +- `.bonsai` - A local Bonsai [environment](https://bonsai-rx.org/docs/articles/environments.html) is required for a script that exports Bonsai workflow images. To create one run these following commands: ```powershell dotnet new install Bonsai.Templates @@ -28,16 +30,13 @@ dotnet new bonsaienv - `.github/workflows` - The docfx website is published to [Github Pages](https://pages.github.com/) using a [Github Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) recipe named [build.yml](https://github.com/bonsai-rx/docs/blob/main/.github/workflows/build.yml). Download `build.yml` and place it in this folder. -Now that your repository is organized, you can move on to setup docfx. - ## Setting up docfx -1) Setup a local installation of `docfx` in your package repo with the following commands (executed in the root directory): +1) Setup a local installation of `docfx` in your package repository with the following commands (executed in the root directory): ```powershell dotnet new tool-manifest dotnet tool install --local docfx ``` -This should create a `.config` folder in the root directory that contains `docfx` version info. 2) Navigate to the `docs` folder and initialise a new DocFx website with the following command. @@ -56,7 +55,7 @@ Enable site search? [y/n] (y): y Enable PDF? [y/n] (y): n ``` -Congrats, you now have a minimal `docfx` website. Run the following command to generate a local preview of the website, and verify that API documentation for your package has been generated successfully: +Congrats! You now have a minimal `docfx` website. Run the following command to generate a local preview of the website, and verify that API documentation for your package has been generated successfully: ```powershell dotnet docfx docfx.json --serve @@ -64,28 +63,28 @@ dotnet docfx docfx.json --serve ### Docfx folder organization -Before proceeding further into customizing the `docfx` website, the `docs` folder should be organised according to this layout for effective long term maintenance. +Before proceeding further into configuring the `docfx` website, the `docs` folder should be organised according to this layout for effective long term maintenance. ``` . -├── api # Automatically generated by docfx -├── apidoc # Place individual operator articles here (add link) -├── articles # Place "Manual" articles here -├── bonsai # Docfx-tools submodule, see note below -├── images # Place images like screenshots here -├── workflow # Store .bonsai workflow files here -├── favicon.ico # Website bookmark logo -├── logo.svg # Website logo -├── template # See note below -│ └── public +├── api/ # Automatically generated by docfx +├── apidoc/ # Place individual operator articles here (see style guide) +├── articles/ # Place "Manual" section articles here (see style guide) +├── bonsai/ # Docfx-tools submodule (see note below) +├── images/ # Place images like screenshots here +├── template/ # Custom CSS template (see note below) +│ └── public/ │ ├── main.css │ └── main.js -├── build.ps1 -└── docfx.json +├── tutorial/ # Place "Tutorials" section articles here (see style guide) +├── workflow/ # Place .bonsai workflow files here for image export +├── build.ps1 # Bonsai workflow image export script (see note below) +├── logo.svg # Website logo +└── favicon.ico # Website bookmark logo ... ``` -`bonsai` - this folder is where we place a submodule that we have created called [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from Bonsai workflows and patches the `docfx` CSS templates to add workflow containers. To add it, run: +- `bonsai` - this folder is where we place a submodule that we have created called [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from `Bonsai` workflows (if you want to include them in your article) and adds a CSS template for `Bonsai` workflow containers (these containers allow users to easily copy workflows into the `Bonsai` editor). To add it, run this command in the `docs` folder: ```powershell git submodule add https://github.com/bonsai-rx/docfx-tools bonsai @@ -95,43 +94,25 @@ If the `bonsai` folder doesnt contain any files, run ```powershell git submodule update --init ``` +- `template` - this custom CSS template patches in docfx-tools and adds a github link to the top right of the navigation bar. Download the [template folder](https://github.com/bonsai-rx/machinelearning/tree/main/docs/template) and amend the github link in `main.css` to your repository. - -6) Copy over these folders/files from a repo that has been recently updated into the root folder of the repo. Amend the files as necessary. - -```markdown -- .gitignore file - this needs to be updated to ignore workflow files (i.e. .bonsai packages env). -``` - -7) Copy over these folders/files from a repo that has been recently updated into the "docs" folder. - -```markdown -- docs/.gitignore file - filters out the _site folder that is generated during local preview. -- docs/workflows/.gitignore file - ignores bonsai layout files and svg files. -- docs/build.ps1 file - script used to export images for sample workflows. - - amend the line in the file to the new package name and source location. -- docs/template/public folder- contains main.css and main.js which patches in `docfx-tools`. - - amend main.js to change the github link to the current repository. -``` +- `build.ps1` - this custom script exports bonsai workflow as images the workflow container. Download the [file](https://github.com/bonsai-rx/pulsepal/blob/main/docs/build.ps1) and amend the line that specifies the package name and source location. ### Configuring docfx -To fully utilize docfx, we have to modify the `docfx.json` file in the `docs` folder, which hosts the configuration options for the website. There are many possible configuration options that can be changed in the `docfx.json`, if in doubt refer to the [docfx documentation](https://dotnet.github.io/docfx/) or a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/). +The `docfx.json` file in the `docs` folder hosts the configuration options for the website and needs to be modified to fully utilize the features availiable. If in doubt, refer to a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) or the [docfx documentation](https://dotnet.github.io/docfx/) for more information. - -1) Add additional files/folders that are to be used in the doc in the `resource` attribute. +1) Modify the `resource` attribute to include files that need to be imported. ```yml -"build": { - "resource": { - "files": [ - "logo.svg", - "favicon.ico", - "images/**", - "workflows/**" - ] - } +"resource": { + "files": [ + "logo.svg", + "favicon.ico", + "images/**", + "workflows/**" + ] } ``` @@ -146,7 +127,7 @@ To fully utilize docfx, we have to modify the `docfx.json` file in the `docs` fo ] ``` -3) Change PackageName and github link to the repo being worked on and add footer information to the `globalMetadata` attribute. +3) Modify the `globalMetadata` attribute to change package name, add the `_gitContribute` attribute with a github repository link, and add the `_appFooter` attribute and description. ```yml "globalMetadata": { @@ -160,7 +141,8 @@ To fully utilize docfx, we have to modify the `docfx.json` file in the `docs` fo } } ``` -4) Enable additional markdig (the default DocFX markdown processor) extensions. + +4) Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(DocFX markdown processor) extensions for additional markdown functionality. ```yml "build": { @@ -173,19 +155,17 @@ To fully utilize docfx, we have to modify the `docfx.json` file in the `docs` fo } ``` -5) Add a `xref` attribute to cross reference operators and properties across the different Bonsai docs websites. +5) Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with docfx documentation, add their `xrefmap.yml` here as well. ```yml "build": { "xref": [ "https://bonsai-rx.org/docs/xrefmap.yml", - "https://horizongir.github.io/reactive/xrefmap.yml" ] } ``` - -Optional: +### Optional configuration options 1) [Filtering Operators](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) - Sometimes in the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. To do so we can add the `filter` attribute to `docfx.json` to filter out nodes in the package. @@ -209,19 +189,13 @@ apiRules: Finally, exclude `filter.yml` from being included in the building of content. ```yml -"build": { - "content": [ - { - "exclude": [ - "_site/**", - "filter.yml" - ] - } - ] -} +"exclude": [ + "_site/**", + "filter.yml" +] ``` -Add the `overwrite` attribute to enable individual operator articles stored in the `apidocs` folder to be included in articles and API docs. +2) Add the `overwrite` attribute to enable individual operator articles stored in the `apidocs` folder to be included in articles and API docs. ```yml "build": { @@ -238,7 +212,34 @@ Add the `overwrite` attribute to enable individual operator articles stored in t ], } ``` -## Testing Unpublished Packages +## Publishing to Github Pages + +Once you are satisfied with the website, publish to github pages. + +1) Setup a new branch called `gh-pages` on your fork of the repository. +2) Go to your repo settings -> `Pages` -> `Build and deployment` - under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. +3) Commit your edits and push to the `main` branch of your repo fork. +4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button. This will build the docs site on the `gh-pages` branch. +5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. +7) The URL for the site can be found in your `Pages` section of your repo settings. + +## Version control cleanup +To keep your online Github repository clean, you can use .gitignore files to ignore files that are generated for documentation that do not need to be version controlled. Add each item as a separate line to the appropriate .gitignore file in each location. +``` +. +├── .bonsai/ +│ └── .gitignore # Packages, *.exe, *.exe.settings, *exe.old (local environment files regenerated by Setup.cmd) +└── docs/ + ├── api/ + │ └── .gitignore # *.yml, .manifest (docfx automatically generated files) + ├── workflows/ + │ └── .gitignore # *.layout, *.svg (bonsai workflow layout files and locally generated images) + └── .gitignore # _site (folder generated by docfx for local preview) +... +``` + +## Testing unpublished packages + To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. Adapted from https://bonsai-rx.org/docs/articles/create-package.html. @@ -248,18 +249,41 @@ Adapted from https://bonsai-rx.org/docs/articles/create-package.html. 4) Press F5 to open the Bonsai editor with the new package added. 5) From here, you can make Bonsai workflows and save them as per normal. -## Publishing to Github Pages -Although this step is not necessary, it can be helpful if you want to check how your edits look online if the local preview is not working. +## Troubleshooting + +### File not found errors + +These are usually due to folders not being in the right place, check the directory trees above or a repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) to make sure that the folders are organised in the right place. Also pay attention to any scripts/css files that require modification of the package name/link/source location. + +### Docfx local preview not updating + +If you are running the local preview `dotnet docfx docfx.json --serve` and not seeing changes: + +1) Make sure that any changes you have made in your code editor are saved. +2) Hard refresh pages in the browser using either Ctrl+Shift+R and Ctrl+F5 or clear the cache to avoid cache issues. +3) As a last resort - check that the content updates online by [publishing your website] (#publishing-to-github-pages). + +### Differences between local and online builds + +If there are discrepancies between local and online builds and they persist, this could indicate a docfx version conflict. The online build process uses a local installation of `docfx` but it is also possible to install `docfx` globally (which we do not recommend). To check if this is the cause of the discrepancy: + +Make sure to run this command which uses the local installation of `docfx` +```powershell +dotnet docfx docfx.json --serve +``` + +Instead of this command which uses the global installation of `docfx`. +```powershell +docfx docfx.json --serve +``` +The `.config` folder in the root directory contains `docfx` local version info if you need to check it. + +If you wish to update the local installation of docfx run this command in the root directory: + +```powershell +dotnet tool update docfx +``` -1) Setup a new branch called `gh-pages` on your fork of the repository. -2) Go to your repo settings -> `Pages` -> `Build and deployment` - under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. -3) Commit your edits and push to the `main` branch of your repo fork. -4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button. This will build the docs site on the `gh-pages` branch. -5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. -7) The URL for the site can be found in your `Pages` section of your repo settings. -## Docfx Troubleshooting -> [!NOTE] -> Occasionally, we run into weird bugs with the local preview. Check if the error persists by [publishing your fork online](#publishing-to-github-pages) \ No newline at end of file From 70ec67cbd82fe1bb1b4d90bbedd14e58f13d42c1 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 11 Sep 2024 16:58:44 -0700 Subject: [PATCH 18/35] Minor edits to TOC, and docfx doc article --- README.md | 10 +- articles/create-package.md | 2 +- ...ocumentation.md => documentation-docfx.md} | 123 +++++++++--------- articles/toc.yml | 2 +- 4 files changed, 67 insertions(+), 70 deletions(-) rename articles/{package-documentation.md => documentation-docfx.md} (76%) diff --git a/README.md b/README.md index 2ab8bad9..21420edb 100644 --- a/README.md +++ b/README.md @@ -7,23 +7,23 @@ This repo contains the technical reference manual for the Bonsai visual programm > [!NOTE] > This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. -Documentation is built using DocFx, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages. +Documentation is built using `docfx`, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages. We welcome all contributions! For more information please refer to our [Contribution Guide](https://bonsai-rx.org/contribute/). # Quick start guide for contributing to documentation -These instructions apply to repos that already have a DocFx website created. +These instructions apply to repos that already have a docfx website created. 1. Fork the repository you want to contribute documentation to. 2. Ensure that you are working off the `main` branch in your fork and create a descriptively named branch for each article/issue that you want to work on. 3. Download and install dotnet (https://dotnet.microsoft.com/en-us/download) -4. Restore the docfx by running +4. Restore `docfx` by running ```powershell dotnet tool restore ``` -4. In a Windows Powershell, use the command `dotnet docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes' +4. In a Windows Powershell, use the command `dotnet docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes. 5. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. 6. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. -For a fuller guide on documentation, check out the [package documentation](./articles/package-documentation.md) article. +For more info, check out the [Documentation with docfx](https://bonsai-rx.org/docs/articles/documentation-docfx.html) and [Documentation Style Guide](https://bonsai-rx.org/docs/articles/documentation-style-guide.html) articles. diff --git a/articles/create-package.md b/articles/create-package.md index bc21cdfc..dc543754 100644 --- a/articles/create-package.md +++ b/articles/create-package.md @@ -98,7 +98,7 @@ The Bonsai language can be extended with custom packages, which are installed an > [!TIP] > Use [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) to document your code. -> Check out the [Documentation with docfx](./package-documentation.md) article for information on how to use [DocFx](https://dotnet.github.io/docfx/index.html) to automatically generate documentation for your package online. +> Check out the [Documentation with docfx](./documentation-docfx.md) article for information on how to use [docfx](https://dotnet.github.io/docfx/index.html) to automatically generate documentation for your package online. ## Publishing a package project diff --git a/articles/package-documentation.md b/articles/documentation-docfx.md similarity index 76% rename from articles/package-documentation.md rename to articles/documentation-docfx.md index d63c7b6b..3307902b 100644 --- a/articles/package-documentation.md +++ b/articles/documentation-docfx.md @@ -1,7 +1,7 @@ # Documentation With Docfx Effective documentation plays a crucial role in driving the adoption and usage of custom packages. Clear, well-organized documentation helps users understand package functionality, integrate it into their workflows, and troubleshoot issues. -For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to support key Bonsai features, we encourage using `docfx` for consistency and support within the Bonsai Ecosystem. +For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to facilitate key Bonsai features, we encourage using `docfx` for consistency and support within the Bonsai Ecosystem. The following article will go into how to create a `docfx` website for your package. For documentation style guidelines, check out the [Documentation Style Guide](./documentation-style-guide.md). @@ -21,14 +21,14 @@ For effective long term maintenance of documentation across different repositori ... ``` -- `.bonsai` - A local Bonsai [environment](https://bonsai-rx.org/docs/articles/environments.html) is required for a script that exports Bonsai workflow images. To create one run these following commands: +- `.bonsai/` - A local Bonsai [environment](https://bonsai-rx.org/docs/articles/environments.html) is required for a script that exports Bonsai workflow images. To create one run these following commands: ```powershell dotnet new install Bonsai.Templates dotnet new bonsaienv ``` -- `.github/workflows` - The docfx website is published to [Github Pages](https://pages.github.com/) using a [Github Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) recipe named [build.yml](https://github.com/bonsai-rx/docs/blob/main/.github/workflows/build.yml). Download `build.yml` and place it in this folder. +- `.github/workflows/` - The docfx website is published to [Github Pages](https://pages.github.com/) using a [Github Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) recipe named [build.yml](https://github.com/bonsai-rx/docs/blob/main/.github/workflows/build.yml). Download `build.yml` and place it in this folder. ## Setting up docfx @@ -38,7 +38,7 @@ dotnet new tool-manifest dotnet tool install --local docfx ``` -2) Navigate to the `docs` folder and initialise a new DocFx website with the following command. +2) Navigate to the `docs` folder and initialise a new docfx website with the following command. ```powershell dotnet docfx init @@ -68,7 +68,7 @@ Before proceeding further into configuring the `docfx` website, the `docs` folde ``` . ├── api/ # Automatically generated by docfx -├── apidoc/ # Place individual operator articles here (see style guide) +├── apidoc/ # Place individual operator articles here (see style guide) ├── articles/ # Place "Manual" section articles here (see style guide) ├── bonsai/ # Docfx-tools submodule (see note below) ├── images/ # Place images like screenshots here @@ -84,7 +84,7 @@ Before proceeding further into configuring the `docfx` website, the `docs` folde ... ``` -- `bonsai` - this folder is where we place a submodule that we have created called [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from `Bonsai` workflows (if you want to include them in your article) and adds a CSS template for `Bonsai` workflow containers (these containers allow users to easily copy workflows into the `Bonsai` editor). To add it, run this command in the `docs` folder: +- `bonsai/` - this folder is where we place a submodule that we have created called [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from `Bonsai` workflows (if you want to include them in your article) and adds a CSS template for `Bonsai` workflow containers (these containers allow users to easily copy workflows into the `Bonsai` editor). To add it, run this command in the `docs` folder: ```powershell git submodule add https://github.com/bonsai-rx/docfx-tools bonsai @@ -94,16 +94,61 @@ If the `bonsai` folder doesnt contain any files, run ```powershell git submodule update --init ``` -- `template` - this custom CSS template patches in docfx-tools and adds a github link to the top right of the navigation bar. Download the [template folder](https://github.com/bonsai-rx/machinelearning/tree/main/docs/template) and amend the github link in `main.css` to your repository. +- `template/` - this custom CSS template patches in docfx-tools and adds a github link to the top right of the navigation bar. Download the [template folder](https://github.com/bonsai-rx/machinelearning/tree/main/docs/template) and amend the github link in `main.css` to your repository. - `build.ps1` - this custom script exports bonsai workflow as images the workflow container. Download the [file](https://github.com/bonsai-rx/pulsepal/blob/main/docs/build.ps1) and amend the line that specifies the package name and source location. ### Configuring docfx -The `docfx.json` file in the `docs` folder hosts the configuration options for the website and needs to be modified to fully utilize the features availiable. If in doubt, refer to a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) or the [docfx documentation](https://dotnet.github.io/docfx/) for more information. +The `docfx.json` file in the `docs` folder hosts the configuration options for the website and needs to be modified to fully utilize the features availiable. If in doubt, refer to a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) or the [docfx documentation](https://dotnet.github.io/docfx/) for more information. These steps are listed in order of appearance in `docfx.json`. -1) Modify the `resource` attribute to include files that need to be imported. +1) Add a `filter` attribute to [filter](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) obsolete operators in the package. Sometimes in the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. + +```yml +"metadata": [ + { + "filter": "filter.yml" + } +] +``` + +Make a file called `filter.yml` with the following lines and place in the `docs` directory. You can also specify other [uids](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) here. + +```yml +apiRules: +- exclude: + hasAttribute: + uid: System.ObsoleteAttribute +``` + +Finally, exclude `filter.yml` from being included in the building of content. + +```yml +"exclude": [ + "_site/**", + "filter.yml" +] +``` +2) Add the `overwrite` attribute to enable [individual operator articles]((./documentation-style-guide.md)) stored in the `apidocs` folder to be included in articles and API docs. + +```yml +"build": { + "overwrite": [ + { + "files": [ + "apidoc/**.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], +} +``` + +3) Modify the `resource` attribute to include files that need to be imported. ```yml "resource": { @@ -116,7 +161,7 @@ The `docfx.json` file in the `docs` folder hosts the configuration options for t } ``` -2) Modify the `template` attribute to use the modern template and apply the `docfx-tools` custom templates to enable workflow containers. +4) Modify the `template` attribute to use the modern template and apply the `docfx-tools` custom templates to enable workflow containers. ```yml "template": [ @@ -127,7 +172,7 @@ The `docfx.json` file in the `docs` folder hosts the configuration options for t ] ``` -3) Modify the `globalMetadata` attribute to change package name, add the `_gitContribute` attribute with a github repository link, and add the `_appFooter` attribute and description. +5) Modify the `globalMetadata` attribute to change package name, add the `_gitContribute` attribute with a github repository link, and add the `_appFooter` attribute and description. ```yml "globalMetadata": { @@ -142,7 +187,7 @@ The `docfx.json` file in the `docs` folder hosts the configuration options for t } ``` -4) Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(DocFX markdown processor) extensions for additional markdown functionality. +6) Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(DocFX markdown processor) extensions for additional markdown functionality. ```yml "build": { @@ -155,7 +200,7 @@ The `docfx.json` file in the `docs` folder hosts the configuration options for t } ``` -5) Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with docfx documentation, add their `xrefmap.yml` here as well. +7) Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with docfx documentation, add their `xrefmap.yml` here as well. ```yml "build": { @@ -165,53 +210,6 @@ The `docfx.json` file in the `docs` folder hosts the configuration options for t } ``` -### Optional configuration options - -1) [Filtering Operators](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) - Sometimes in the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. To do so we can add the `filter` attribute to `docfx.json` to filter out nodes in the package. - -```yml -"metadata": [ - { - "filter": "filter.yml" - } -] -``` - -Make a file called `filter.yml` with content such as below and place in the `docs` directory. - -```yml -apiRules: -- exclude: - hasAttribute: - uid: System.ObsoleteAttribute -``` - -Finally, exclude `filter.yml` from being included in the building of content. - -```yml -"exclude": [ - "_site/**", - "filter.yml" -] -``` - -2) Add the `overwrite` attribute to enable individual operator articles stored in the `apidocs` folder to be included in articles and API docs. - -```yml -"build": { - "overwrite": [ - { - "files": [ - "apidoc/**.md" - ], - "exclude": [ - "obj/**", - "_site/**" - ] - } - ], -} -``` ## Publishing to Github Pages Once you are satisfied with the website, publish to github pages. @@ -240,8 +238,7 @@ To keep your online Github repository clean, you can use .gitignore files to ign ## Testing unpublished packages -To write documentation for new packages or releases that have not been published to the community, test them in Visual Studio. -Adapted from https://bonsai-rx.org/docs/articles/create-package.html. +To write documentation for [new packages or releases](https://bonsai-rx.org/docs/articles/create-package.html) that have not been published to the community, test them in Visual Studio. 1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free). 2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. @@ -254,7 +251,7 @@ Adapted from https://bonsai-rx.org/docs/articles/create-package.html. ### File not found errors -These are usually due to folders not being in the right place, check the directory trees above or a repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) to make sure that the folders are organised in the right place. Also pay attention to any scripts/css files that require modification of the package name/link/source location. +These are usually due to folders not being in the right place, check the directory trees above or a repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) for reference. Also pay attention to any scripts/css files that require modification of the package name/link/source location. ### Docfx local preview not updating diff --git a/articles/toc.yml b/articles/toc.yml index eed66458..a4b29b02 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -34,7 +34,7 @@ - name: Creating a Package href: create-package.md - name: Documentation With Docfx - href: package-documentation.md + href: documentation-docfx.md - name: Documentation Style Guide href: documentation-style-guide.md - name: Design Guidelines From a9eb2c0f01161621bef6001fc672142fdc5a7ada Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 12 Sep 2024 14:15:04 -0700 Subject: [PATCH 19/35] Expand documentation style article --- README.md | 6 +- articles/documentation-docfx.md | 5 +- articles/documentation-style-guide.md | 95 ++++++++++++++++----------- 3 files changed, 63 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 21420edb..e937ca60 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,8 @@ These instructions apply to repos that already have a docfx website created. ```powershell dotnet tool restore ``` -4. In a Windows Powershell, use the command `dotnet docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes. -5. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. -6. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. +5. In a Windows Powershell, use the command `dotnet docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes. +6. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. +7. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. For more info, check out the [Documentation with docfx](https://bonsai-rx.org/docs/articles/documentation-docfx.html) and [Documentation Style Guide](https://bonsai-rx.org/docs/articles/documentation-style-guide.html) articles. diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 3307902b..17d7e2ca 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -1,7 +1,6 @@ # Documentation With Docfx -Effective documentation plays a crucial role in driving the adoption and usage of custom packages. Clear, well-organized documentation helps users understand package functionality, integrate it into their workflows, and troubleshoot issues. -For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to facilitate key Bonsai features, we encourage using `docfx` for consistency and support within the Bonsai Ecosystem. +Effective online documentation plays a crucial role in driving the adoption and usage of custom packages. For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to facilitate key Bonsai features, we encourage package developers to use `docfx` for consistency and support within the Bonsai Ecosystem. The following article will go into how to create a `docfx` website for your package. For documentation style guidelines, check out the [Documentation Style Guide](./documentation-style-guide.md). @@ -130,7 +129,7 @@ Finally, exclude `filter.yml` from being included in the building of content. "filter.yml" ] ``` -2) Add the `overwrite` attribute to enable [individual operator articles]((./documentation-style-guide.md)) stored in the `apidocs` folder to be included in articles and API docs. +2) Add the `overwrite` attribute to enable [individual operator articles](./documentation-style-guide.md) stored in the `apidocs` folder to be included in articles and API docs. ```yml "build": { diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index dfc833cf..64472bc2 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -1,15 +1,21 @@ # Documentation Style Guide -## Article Organization +Clear, well-organized documentation helps users understand package functionality, integrate it into their workflows, and troubleshoot effectively. -The navigation bar at the top of the DocFX website should have 2-3 links to the main pages of the website. +Through our experience documenting Bonsai, we've established several best practices for presenting information, which are outlined here alongside practical methods for implementation in [docfx](./documentation-docfx.md). This document is intended as a living resource, open to feedback and continuous improvement, rather than a static guide. Click on the `Edit this page` button or raise an issue on the [bonsai-docs](https://github.com/bonsai-rx/docs/issues) repository if you have a suggestion. -* Manual - hosts documentation that explains the basic functions of the various operators in the package. -* Reference - generated automatically by DocFX from XML comments in the Bonsai package source code. -* Tutorials - optional page that would have examples or tutorials for various applications. +## Article organization +In general, we have found that three types of articles, organized into distinct website sections, are sufficient to address the needs of most users and their learning styles. -To construct the navigation bar, edit the `docs/toc.yml` file to reflect the location and name of the various pages. +* Manual - hosts documentation that explains the basic workflow of the package or functions of the various operators. +* Reference - hosts technical documentation for each operator, generated automatically by DocFX from XML comments in source code or supplemented with individual operator articles. +* Tutorials - hosts examples or tutorials for various applications. This section is optional, but valuable for more complicated applications or packages which require operators from other packages for their execution. + +To construct these 3 sections: + +1) Ensure that the `docs` folder has a `articles` and `tutorials` folder. The `api` folder is automatically generated. +2) For the navigation bar at the top of the website, edit the `docs/toc.yml` file to reflect the location and name of the various folders. ```yml - name: Manual @@ -17,65 +23,80 @@ To construct the navigation bar, edit the `docs/toc.yml` file to reflect the loc - name: Reference href: api/ - name: Tutorials - href: articles/tutorials/ + href: tutorials/ ``` - -### Table of contents -For the `Manual` and `Tutorials` pages of the website, the table of contents is built from a `toc.yml` file located in the respective folders. The table of contents for the API page is generated automatically. - -Getting started/Landing page - the first page of the docs website will be an `index.md` file that is located in the `docs` folder. This typically includes a description of what the package does, installation instructions (if not too complicated) and acknowledgements. To make this page the landing page, in the `articles/toc.yml` file, the getting started page should be listed as shown. This step is omitted from the tutorials `toc.yml`. +3) Add articles in markdown format to the `Manual` and `Tutorials` folder +4) Add a toc.yml file to the `Manual` and `Tutorials` folder to generate the table of contents for that section. The `API` toc.yml is generated automatically. +Here is a sample `articles/toc.yml` with a flattened table of content layout (all articles will be visible in the TOC) ```yml -- href: ../index.md +- href: ../index.md # Website Getting Started page that points to docs/index.md. Omit for tutorials/toc.yml +- name: LinearDynamicalSystems # Group Heading (Optional) +- href: lds-overview.md # Article filename +- href: lds-installation-guide-windows.md +- href: lds-installation-guide-linux.md ``` -> [!NOTE] -> Article names can be omitted as they will be taken from the first `Heading 1` element in the article. - -For the rest of the articles, they can be added to the articles folder and referred to as follows. -Article filenames should be simple and reflect either the article title or operator name (if the article is about a specific operator). +Here is a same `toc.yml` but this time with a nested table of content layout (articles will only be visible when group headings are clicked) ```yml -- href: ../index.md -- href: lds-overview.md +- href: ../index.md +- name: LinearDynamicalSystems + items: + - href: lds-overview.md + - href: lds-installation-guide-windows.md + - href: lds-installation-guide-linux.md ``` +> [!TIP] +> Article filenames should be simple and reflect either the article title or operator name. Titles can be omitted as they will be taken from the first `Heading 1` element. -To organise articles into different sections, simply include a name before the links to the articles that you want to group together. +### Manual articles -```yml -- href: ../index.md -- name: LinearDynamicalSystems -- href: lds-overview.md -- href: lds-installation-guide-windows.md -- href: lds-installation-guide-linux.md -``` +For the `Manual` section we typically see these elements: -> [!NOTE] -> While there is another method of grouping articles together that makes a nested table of contents, we prefer this method as it expands the table of contents so that users can see all the articles at once and get to them quicker. +- Getting Started/Landing page - This typically includes a description of what the package does, how to install the package and funding/acknowledgements. +- Installation Instructions - If a package requires external dependencies or additional configuration it would be helpful to dedicate an extra page to this. +- Workflow Overview - Best illustrated with a flowchart or a basic workflow container -### Individual Bonsai operator articles -Where possible, documentation should be written for individual Bonsai operators and embedded in the `Manual` articles. The advantage of this approach is that documentation for individual operators will be appended to the automatically generated `Reference` API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. +Beyond that, there are many possible ways to organise the rest of the manual articles depending on the type of package that is being supported. However one approach that we recommend regardless, is to try and write articles for each individual operator. This approach has several advantages: -For example, to create documentation for a `PredictPoses` operator that will be included in a `Network Inference` article for the `Bonsai.Sleap` package: +- individual operator articles can be integrated into the automatically generated `Reference` documentation using docfx's `overwrite` function, allowing for supplemental content like images and workflows. +- These articles can also be combined into larger conceptual guides, providing organizational flexibility. +- Writing individual operator articles ensures complete coverage of all operators. -1) Create a `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. In the markdown file, assign a UID that follows the namespace.operator format. +Creating an individual operator article requires some +For example, to create an individual operator article for a `PredictPoses` operator that will be included in a "Network Inference" `Manual` article as well as +as in the automatically generated `Reference` doc: + +1) **Create the Operator Article** - `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the namespace.operator format. ```yml --- uid: Bonsai.Sleap.PredictPoses --- - Write content here. ``` 2) Create a `Network-Inference.md` article and place it in the `docs\articles` folder. In the markdown file, include a reference to the individual operator.md file. -```yml +```markdown +Other [!include[Title](~/apidoc/Bonsai_Sleap_PredictPoses.md)] ``` > [!NOTE] > The title is optional. +### Reference articles + +A unique + +The advantage of this approach is that documentation for individual operators will be appended to the automatically generated `Reference` API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. + + + + + + ### Tutorials/Examples Submodule For packages with extensive tutorials, a separate repository can be created and imported as a submodule. This may be especially helpful if they contain multimedia and other large files. @@ -87,7 +108,7 @@ git submodule add https://github.com/bonsai-rx/machinelearning-examples In addition, the `docfx.json` file needs to be modified. For an example of how to setup a Tutorial submodule, refer to https://github.com/bonsai-rx/machinelearning and its submodule https://github.com/bonsai-rx/machinelearning-examples. -## Contributor Style Guide +## Article Style Guide > [!NOTE] > When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic that could possibly be used as a reference. From 73cf304818ccd6f111e760d6d40067d1a49a1edd Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 16 Sep 2024 14:09:16 -0700 Subject: [PATCH 20/35] Update doc style guide with cross-referencing --- articles/documentation-style-guide.md | 90 ++++++++++++++++++--------- 1 file changed, 61 insertions(+), 29 deletions(-) diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index 64472bc2..63e0f1cf 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -50,7 +50,7 @@ Here is a same `toc.yml` but this time with a nested table of content layout (ar > [!TIP] > Article filenames should be simple and reflect either the article title or operator name. Titles can be omitted as they will be taken from the first `Heading 1` element. -### Manual articles +### Manual section For the `Manual` section we typically see these elements: @@ -58,17 +58,20 @@ For the `Manual` section we typically see these elements: - Installation Instructions - If a package requires external dependencies or additional configuration it would be helpful to dedicate an extra page to this. - Workflow Overview - Best illustrated with a flowchart or a basic workflow container -Beyond that, there are many possible ways to organise the rest of the manual articles depending on the type of package that is being supported. However one approach that we recommend regardless, is to try and write articles for each individual operator. This approach has several advantages: +Beyond that, there are many possible ways to organise the rest of the manual articles depending on the type of package that is being supported. + +#### Individual operator articles + +One approach that we recommend is to try and write articles for each individual operator. This approach has several advantages: - individual operator articles can be integrated into the automatically generated `Reference` documentation using docfx's `overwrite` function, allowing for supplemental content like images and workflows. -- These articles can also be combined into larger conceptual guides, providing organizational flexibility. +- These articles can also be combined into larger conceptual `Manual` articles, providing organizational flexibility. - Writing individual operator articles ensures complete coverage of all operators. -Creating an individual operator article requires some -For example, to create an individual operator article for a `PredictPoses` operator that will be included in a "Network Inference" `Manual` article as well as -as in the automatically generated `Reference` doc: +Creating an individual operator article requires some additional steps. +For example, to create an individual operator article for a `PredictPoses` operator that will be included in a "Network Inference" `Manual` article as well as in the automatically generated `Reference` doc: -1) **Create the Operator Article** - `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the namespace.operator format. +1) Create the `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the namespace.operator format. ```yml --- @@ -86,39 +89,67 @@ Other > [!NOTE] > The title is optional. -### Reference articles +### Reference section -A unique +As mentioned the `Reference` section of the website is auto-generated from [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) in the code. A unique feature we have integrated into the Bonsai Editor is that when users when users right click on individual operators they will be shown the `Reference` page for that operator. For many users, this might be the most obvious entry point to the package documentation. Thus it is essential that developers ensure that: -The advantage of this approach is that documentation for individual operators will be appended to the automatically generated `Reference` API docs. In addition, they will also show up in the Bonsai editor when users right click on individual operators to `View Help`. +1) XML documentation comments are clear, simple and helpful. +2) Where appropriate, supplement additional information (basic workflow, images, long-form content) with an individual operator article using the `overwrite` function detailed in the previous section. +At present, we understand that the default template for the `Reference` page is a little too technically oriented, and somewhat confusing for Bonsai users to navigate. We are in the midst of revamping the template to cater to a broader audience and will update this section when it becomes availiable. +### Tutorials section +#### Submodule +For packages with extensive tutorials, multimedia and other large files, a separate repository can be created and imported as a submodule. +A tutorial submodule can be added with the following command in the `docs` directory: -### Tutorials/Examples Submodule -For packages with extensive tutorials, a separate repository can be created and imported as a submodule. -This may be especially helpful if they contain multimedia and other large files. -A tutorial submodule can be added with the following command. - -```cmd +```powershell git submodule add https://github.com/bonsai-rx/machinelearning-examples ``` -In addition, the `docfx.json` file needs to be modified. -For an example of how to setup a Tutorial submodule, refer to https://github.com/bonsai-rx/machinelearning and its submodule https://github.com/bonsai-rx/machinelearning-examples. +In addition, the `docfx.json` file needs to be modified to import the relevant resources. For an example of how to setup a Tutorial submodule, refer to the [Bonsai Machine Learning Package](https://github.com/bonsai-rx/machinelearning) package and its submodule [Machine Learning Examples](https://github.com/bonsai-rx/machinelearning-examples). -## Article Style Guide +## Article formatting guide -> [!NOTE] -> When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic that could possibly be used as a reference. +In docfx, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine. Refer to these links for more information on how to format content in markdown. -With DocFX, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine that supports additional markdown extensions. When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: +When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: - Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) - Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. - Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". +### Cross-references and highlights + +When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist that could be linked if it would be helpful and to avoid duplication. Link resources like websites for external libraries for users to explore for more information. + +**Example:** + +To create a hyperlink in markdown use the following syntax: + +```markdown +[docfx](https://dotnet.github.io/docfx/) +``` +To link to an article within the same website, use relative links to the markdown file: + +```markdown +[Create a package](./create-package.md) +``` + +To link to a section within the same article, use the section heading anchor which looks like this (`#section-heading-lowercase`): + +```markdown +[Article formatting guide](#article-formatting-guide). +``` + +Highlight folders, filenames, package names, functions, actions, editor/website sections with backticks: + +```markdown +`docfx` +``` + ### Standard formatting for operators and operator properties When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). @@ -138,10 +169,12 @@ When referring to operator properties, simply place the operator property name i - Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator. ``` +You can also link to operators in other packages if their [xrefmap](./documentation-docfx.md#configuring-docfx) is included in `docfx.json`. + ### Bonsai workflows To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName_workflowName`. -Add the `.bonsai` file to the **workflows** folder in the repo. In the text of the article that includes/references this example workflow, add a workflow container. +Add the `.bonsai` file to the `workflows` folder in the repository. In the text of the article that includes/references this example workflow, add a workflow container. **Example:** @@ -154,11 +187,9 @@ Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: ``` Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. -If any of the nodes are greyed out in the SVG images when published, then the `config.yml` file in the `.Bonsai` folder needs to be updated. -For instance, if you used a `KeyDown` operator in your sample Bonsai workflow, the `Bonsai.Windows.Input` package needs to be included. +If any of the nodes are greyed out in the SVG images when published, then additional packages need to be installed in the [local bonsai environment](./documentation-docfx.md#repository-organization). -Navigate to your local Bonsai installation folder, and you will find a `config.yml` that includes the necessary information to copy over to the `config.yml` file in `.bonsai` folder. -Only copy the lines that reference the package. +Simply open `bonsai.exe` in the `.bonsai` folder, go to the package manager and install the package. ### Figures @@ -168,7 +199,7 @@ Only copy the lines that reference the package. To include a figure or image in an article: 1) Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. -2) Add the figure/image to the **images** folder in the repo. +2) Add the figure/image to the `images` folder in the repo. 3) Reference the figure in the article with the following code. 4) (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. @@ -236,8 +267,9 @@ Highlight properties to change for a particular application by representing them | Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | ### Code snippets -Use code blocks to highlight code to run. Enable language specific highlighting by adding a language identifier at the beginning. +Use code blocks to highlight code to run. Enable [language specific highlighting]() by adding a language identifier at the beginning. +**Example:** ````markdown ```powershell dotnet new tool-manifest From 4d13261fb7707cd55e724c1da2103b8536229cd4 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 16 Sep 2024 15:29:36 -0700 Subject: [PATCH 21/35] Fix broken section anchor in docfx doc guide --- articles/documentation-docfx.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 17d7e2ca..c788b613 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -258,7 +258,7 @@ If you are running the local preview `dotnet docfx docfx.json --serve` and not s 1) Make sure that any changes you have made in your code editor are saved. 2) Hard refresh pages in the browser using either Ctrl+Shift+R and Ctrl+F5 or clear the cache to avoid cache issues. -3) As a last resort - check that the content updates online by [publishing your website] (#publishing-to-github-pages). +3) As a last resort - check that the content updates online by [publishing your website](#publishing-to-github-pages). ### Differences between local and online builds From 1388d0bdf0327156fba80cead35ab1acd0872d40 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Sep 2024 23:40:50 -0700 Subject: [PATCH 22/35] Minor edits for clarity and grammar --- articles/documentation-docfx.md | 80 +++++++++++++++------------ articles/documentation-style-guide.md | 37 +++++++++---- 2 files changed, 71 insertions(+), 46 deletions(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index c788b613..8c56d55c 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -9,11 +9,12 @@ The following article will go into how to create a `docfx` website for your pack ## Repository organization For effective long term maintenance of documentation across different repositories, package repositories should be organised according to this standardized folder structure before setting up `docfx`: + ``` . ├── .bonsai/ # Local Bonsai Environment (see note below) ├── .github/workflows/ # Github Actions Folder (see note below) -│ └── build.yml +│ └── docs.yml ├── docs/ # Folder to setup docfx └── src/ └── Bonsai.PackageName/ # Project files here @@ -27,11 +28,12 @@ dotnet new install Bonsai.Templates dotnet new bonsaienv ``` -- `.github/workflows/` - The docfx website is published to [Github Pages](https://pages.github.com/) using a [Github Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) recipe named [build.yml](https://github.com/bonsai-rx/docs/blob/main/.github/workflows/build.yml). Download `build.yml` and place it in this folder. +- `.github/workflows/` - The docfx website is published to [Github Pages](https://pages.github.com/) using a [Github Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow called `docs.yml`. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend `Bonsai.PackageName` to point to your package source code in `docs.yml`. ## Setting up docfx 1) Setup a local installation of `docfx` in your package repository with the following commands (executed in the root directory): + ```powershell dotnet new tool-manifest dotnet tool install --local docfx @@ -88,21 +90,29 @@ Before proceeding further into configuring the `docfx` website, the `docs` folde ```powershell git submodule add https://github.com/bonsai-rx/docfx-tools bonsai ``` -If the `bonsai` folder doesnt contain any files, run +If you cloned the repository and the `bonsai` folder does not contain any files: ```powershell git submodule update --init ``` -- `template/` - this custom CSS template patches in docfx-tools and adds a github link to the top right of the navigation bar. Download the [template folder](https://github.com/bonsai-rx/machinelearning/tree/main/docs/template) and amend the github link in `main.css` to your repository. -- `build.ps1` - this custom script exports bonsai workflow as images the workflow container. Download the [file](https://github.com/bonsai-rx/pulsepal/blob/main/docs/build.ps1) and amend the line that specifies the package name and source location. +To update the submodule to the latest commit: +```powershell +git submodule update --remote +``` + +- `template/` - this custom CSS template patches in docfx-tools and adds a github link to the top right of the navigation bar. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the github link in `main.css` to your repository. + +- `build.ps1` - this custom script exports bonsai workflow as images the workflow container. Download the file from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the line that specifies the package name and source location. + +- `logo.svg` and `favicon.ico` - for official Bonsai packages these can be downloaded from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository. ### Configuring docfx The `docfx.json` file in the `docs` folder hosts the configuration options for the website and needs to be modified to fully utilize the features availiable. If in doubt, refer to a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) or the [docfx documentation](https://dotnet.github.io/docfx/) for more information. These steps are listed in order of appearance in `docfx.json`. -1) Add a `filter` attribute to [filter](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) obsolete operators in the package. Sometimes in the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. +1) Add a `filter` attribute to [filter](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) obsolete operators in the package. In the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. ```yml "metadata": [ @@ -121,17 +131,23 @@ apiRules: uid: System.ObsoleteAttribute ``` -Finally, exclude `filter.yml` from being included in the building of content. +2) Exclude these files from being included in the building of content to avoid duplicate errors. -```yml -"exclude": [ - "_site/**", - "filter.yml" -] +```json +"build": { + "content": [ + "exclude": [ + "_site/**", + "filter.yml", + "apidoc/**" + ] + ] +} ``` -2) Add the `overwrite` attribute to enable [individual operator articles](./documentation-style-guide.md) stored in the `apidocs` folder to be included in articles and API docs. -```yml +3) Add the `overwrite` attribute to enable [individual operator articles](./documentation-style-guide.md) stored in the `apidocs` folder to be included in articles and API docs. + +```json "build": { "overwrite": [ { @@ -147,9 +163,9 @@ Finally, exclude `filter.yml` from being included in the building of content. } ``` -3) Modify the `resource` attribute to include files that need to be imported. +4) Modify the `resource` attribute to include files that need to be imported. -```yml +```json "resource": { "files": [ "logo.svg", @@ -160,9 +176,9 @@ Finally, exclude `filter.yml` from being included in the building of content. } ``` -4) Modify the `template` attribute to use the modern template and apply the `docfx-tools` custom templates to enable workflow containers. +5) Modify the `template` attribute to use the modern template and apply the `docfx-tools` custom templates to enable workflow containers. -```yml +```json "template": [ "default", "modern", @@ -171,24 +187,19 @@ Finally, exclude `filter.yml` from being included in the building of content. ] ``` -5) Modify the `globalMetadata` attribute to change package name, add the `_gitContribute` attribute with a github repository link, and add the `_appFooter` attribute and description. +6) Modify the `globalMetadata` attribute to change package name and add the `_appFooter` attribute and description. -```yml +```json "globalMetadata": { "_appName": "Bonsai - PackageName", "_appTitle": "Bonsai.PackageName", - "_appFooter": "© 2024 Bonsai Foundation CIC and Contributors. Made with docfx", - "_gitContribute": { - "repo": "https://github.com/bonsai-rx/PackageName", - "branch": "main", - "apiSpecFolder": "apidoc" - } + "_appFooter": "© 2024 Bonsai Foundation CIC and Contributors. Made with docfx" } ``` -6) Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(DocFX markdown processor) extensions for additional markdown functionality. +7) Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(DocFX markdown processor) extensions for additional markdown functionality. -```yml +```json "build": { "markdownEngineProperties": { "markdigExtensions": [ @@ -199,9 +210,9 @@ Finally, exclude `filter.yml` from being included in the building of content. } ``` -7) Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with docfx documentation, add their `xrefmap.yml` here as well. +8) Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with docfx documentation, add their `xrefmap.yml` here as well. -```yml +```json "build": { "xref": [ "https://bonsai-rx.org/docs/xrefmap.yml", @@ -211,21 +222,22 @@ Finally, exclude `filter.yml` from being included in the building of content. ## Publishing to Github Pages -Once you are satisfied with the website, publish to github pages. +Once you are satisfied with the website, publish to [Github Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site). A Github Actions workflow has already been created, make sure `docs.yml` is in the `.github/workflows` [folder](#repository-organization). 1) Setup a new branch called `gh-pages` on your fork of the repository. 2) Go to your repo settings -> `Pages` -> `Build and deployment` - under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. -3) Commit your edits and push to the `main` branch of your repo fork. -4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button. This will build the docs site on the `gh-pages` branch. +3) Commit your edits and push them online. +4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button on the branch you commited your edits to. This will build the docs site on the `gh-pages` branch. 5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. 7) The URL for the site can be found in your `Pages` section of your repo settings. ## Version control cleanup To keep your online Github repository clean, you can use .gitignore files to ignore files that are generated for documentation that do not need to be version controlled. Add each item as a separate line to the appropriate .gitignore file in each location. + ``` . ├── .bonsai/ -│ └── .gitignore # Packages, *.exe, *.exe.settings, *exe.old (local environment files regenerated by Setup.cmd) +│ └── .gitignore # Packages, *.exe, *.exe.settings, *.exe.old (local environment files regenerated by Setup.cmd) └── docs/ ├── api/ │ └── .gitignore # *.yml, .manifest (docfx automatically generated files) diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index 63e0f1cf..034bce91 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -25,9 +25,9 @@ To construct these 3 sections: - name: Tutorials href: tutorials/ ``` -3) Add articles in markdown format to the `Manual` and `Tutorials` folder +3) Add articles in markdown format to the `Manual` and `Tutorials` folder. 4) Add a toc.yml file to the `Manual` and `Tutorials` folder to generate the table of contents for that section. The `API` toc.yml is generated automatically. -Here is a sample `articles/toc.yml` with a flattened table of content layout (all articles will be visible in the TOC) +Here is a sample `articles/toc.yml` with a flattened table of content layout (all articles will be visible in the TOC). This works best for most websites which do not have a lot of articles. ```yml - href: ../index.md # Website Getting Started page that points to docs/index.md. Omit for tutorials/toc.yml @@ -36,8 +36,13 @@ Here is a sample `articles/toc.yml` with a flattened table of content layout (al - href: lds-installation-guide-windows.md - href: lds-installation-guide-linux.md ``` +> [!TIP] +> Setting up the link to the `Getting Started` page in this way avoids having to create a separate, redundant landing page. + +> [!TIP] +> Article filenames should be simple and reflect either the article title or operator name. Titles can be omitted as they will be taken from the first `Heading 1` element. -Here is a same `toc.yml` but this time with a nested table of content layout (articles will only be visible when group headings are clicked) +Here is a same `toc.yml` but this time with a nested table of content layout (articles will only be visible when group headings are clicked). ```yml - href: ../index.md @@ -47,16 +52,14 @@ Here is a same `toc.yml` but this time with a nested table of content layout (ar - href: lds-installation-guide-windows.md - href: lds-installation-guide-linux.md ``` -> [!TIP] -> Article filenames should be simple and reflect either the article title or operator name. Titles can be omitted as they will be taken from the first `Heading 1` element. ### Manual section For the `Manual` section we typically see these elements: -- Getting Started/Landing page - This typically includes a description of what the package does, how to install the package and funding/acknowledgements. +- Getting Started/Landing page - This typically includes a description of what the package does, how to install the package and funding/acknowledgements. This belongs in `docs/index.md`. - Installation Instructions - If a package requires external dependencies or additional configuration it would be helpful to dedicate an extra page to this. -- Workflow Overview - Best illustrated with a flowchart or a basic workflow container +- Workflow/Conceptual Overview - Best illustrated with a flowchart or a basic workflow container. Beyond that, there are many possible ways to organise the rest of the manual articles depending on the type of package that is being supported. @@ -100,6 +103,7 @@ At present, we understand that the default template for the `Reference` page is ### Tutorials section +For the tutorials section, we suggest creating individual pages for various applications where the package is likely to be used. For each application, guide learners through the workflow step by step, organizing it into separate exercises with clear objectives and visible results. This structure makes the content more accessible and manageable for learners, especially for complex workflows. #### Submodule For packages with extensive tutorials, multimedia and other large files, a separate repository can be created and imported as a submodule. @@ -109,6 +113,7 @@ A tutorial submodule can be added with the following command in the `docs` direc ```powershell git submodule add https://github.com/bonsai-rx/machinelearning-examples ``` + In addition, the `docfx.json` file needs to be modified to import the relevant resources. For an example of how to setup a Tutorial submodule, refer to the [Bonsai Machine Learning Package](https://github.com/bonsai-rx/machinelearning) package and its submodule [Machine Learning Examples](https://github.com/bonsai-rx/machinelearning-examples). ## Article formatting guide @@ -132,6 +137,7 @@ To create a hyperlink in markdown use the following syntax: ```markdown [docfx](https://dotnet.github.io/docfx/) ``` + To link to an article within the same website, use relative links to the markdown file: ```markdown @@ -173,21 +179,28 @@ You can also link to operators in other packages if their [xrefmap](./documentat ### Bonsai workflows -To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName_workflowName`. +To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName-workflowName`. Add the `.bonsai` file to the `workflows` folder in the repository. In the text of the article that includes/references this example workflow, add a workflow container. **Example:** -Assuming you want to include `custom-pulse-train_send-custom-waveform.bonsai`: +Assuming you want to include `CustomPulseTrain-SendCustomWaveform.bonsai`: ```markdown :::workflow -![Send Custom Waveform](../workflows/custom-pulse-train_send-custom-waveform.bonsai) +![Send Custom Waveform](../workflows/CustomPulseTrain-SendCustomWaveform.bonsai) ::: ``` -Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. -If any of the nodes are greyed out in the SVG images when published, then additional packages need to be installed in the [local bonsai environment](./documentation-docfx.md#repository-organization). +Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule and requires the `build.ps1`(./documentation-docfx.md#docfx-folder-organization) file and a [local bonsai environment](./documentation-docfx.md#repository-organization). + +To generate the images locally for the `docfx` local preview, navigate to the `docs` folder and run this command (make sure `build.ps1` has been modified to point to the package src): + +```powershell +./build.ps1 +``` + +If any of the nodes are greyed out in the generated SVG, then additional packages need to be installed in the local bonsai environment. Simply open `bonsai.exe` in the `.bonsai` folder, go to the package manager and install the package. From a8462427c2b79c8eb8f27d873af51bc992d752f1 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 19 Sep 2024 13:32:07 -0700 Subject: [PATCH 23/35] Minor edits to clarity and formatting --- articles/documentation-docfx.md | 7 +++++-- articles/documentation-style-guide.md | 29 +++++++++++++++++++++------ 2 files changed, 28 insertions(+), 8 deletions(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 8c56d55c..5e20c963 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -229,7 +229,10 @@ Once you are satisfied with the website, publish to [Github Pages](https://docs. 3) Commit your edits and push them online. 4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button on the branch you commited your edits to. This will build the docs site on the `gh-pages` branch. 5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. -7) The URL for the site can be found in your `Pages` section of your repo settings. +7) The URL for the site can be found in your `Pages` section of your repository settings. + +> [!NOTE] +> To ensure that the Bonsai Editor can link to the `Reference` documentation for operators, make sure that the `PackageProjectURL` in either the `.csproj` file or the `Directory.Build.props` file points to the URL for the documentation website. ## Version control cleanup To keep your online Github repository clean, you can use .gitignore files to ignore files that are generated for documentation that do not need to be version controlled. Add each item as a separate line to the appropriate .gitignore file in each location. @@ -253,7 +256,7 @@ To write documentation for [new packages or releases](https://bonsai-rx.org/docs 1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free). 2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. -3) In Visual Studio, open `src/PackageName.sln` in the repo. +3) In Visual Studio, open `src/PackageName.sln` in the repository. 4) Press F5 to open the Bonsai editor with the new package added. 5) From here, you can make Bonsai workflows and save them as per normal. diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index 034bce91..0f1fd858 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -74,7 +74,7 @@ One approach that we recommend is to try and write articles for each individual Creating an individual operator article requires some additional steps. For example, to create an individual operator article for a `PredictPoses` operator that will be included in a "Network Inference" `Manual` article as well as in the automatically generated `Reference` doc: -1) Create the `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs\apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the namespace.operator format. +1) Create the `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs/apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the namespace.operator format. ```yml --- @@ -83,11 +83,11 @@ uid: Bonsai.Sleap.PredictPoses Write content here. ``` -2) Create a `Network-Inference.md` article and place it in the `docs\articles` folder. In the markdown file, include a reference to the individual operator.md file. +2) Create a `Network-Inference.md` article and place it in the `docs/articles` folder. In the markdown file, include a reference to the individual operator.md file. ```markdown Other -[!include[Title](~/apidoc/Bonsai_Sleap_PredictPoses.md)] +[!include[Title](../apidoc/Bonsai_Sleap_PredictPoses.md)] ``` > [!NOTE] > The title is optional. @@ -126,6 +126,23 @@ When writing articles, please follow the [MSDN writing tips](https://learn.micro - Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. - Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". +### Linking content +When linking to content (either images, or other articles, or workflow containers) use relative paths in this format: + +**Example:** + +For content in the same folder: + +```markdown +./content.md +``` + +For content in a different folder, use `../` to navigate up to the parent folder, and then specify the folder with the content like this: + +```markdown +../images/bonsai-screenshot.svg +``` + ### Cross-references and highlights When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist that could be linked if it would be helpful and to avoid duplication. Link resources like websites for external libraries for users to explore for more information. @@ -219,7 +236,7 @@ To include a figure or image in an article: **Example:** ```markdown -!['Editor Gallery'](~/images/editor-gallery.png){width=500} +!['Editor Gallery'](../images/editor-gallery.png){width=500} ``` ### Diagrams and Charts @@ -280,7 +297,7 @@ Highlight properties to change for a particular application by representing them | Pulse Timing | `PulseTrainDuration`| 0.0001 - 3600 (secs) | The duration of the pulse train. | ### Code snippets -Use code blocks to highlight code to run. Enable [language specific highlighting]() by adding a language identifier at the beginning. +Use code blocks to highlight code to run. Enable [language specific highlighting](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) by adding a language identifier at the beginning. **Example:** ````markdown @@ -292,7 +309,7 @@ dotnet tool install --local docfx --version 2.75.3 ### Alerts -Use alerts to alert users to important information. Only use either the `Note` or `Warning` alerts as they do not conflict with the formatting for property names. +Use alerts to alert users to important information. Only use either the `Note` or `Warning` alerts as the color scheme does not conflict with the formatting for property names. **Example:** ```markdown From 8b28c16dc48cea640f6dce8225c00a0f7497efc5 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 20 Sep 2024 22:06:17 -0700 Subject: [PATCH 24/35] Clarify build.ps1 purpose --- articles/documentation-docfx.md | 2 +- articles/documentation-style-guide.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 5e20c963..e538146e 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -103,7 +103,7 @@ git submodule update --remote - `template/` - this custom CSS template patches in docfx-tools and adds a github link to the top right of the navigation bar. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the github link in `main.css` to your repository. -- `build.ps1` - this custom script exports bonsai workflow as images the workflow container. Download the file from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the line that specifies the package name and source location. +- `build.ps1` - this custom script exports Bonsai workflow images using `docfx-tools` and then calls the docfx build process. Download the file from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the line that specifies the package name and source location. - `logo.svg` and `favicon.ico` - for official Bonsai packages these can be downloaded from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository. diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index 0f1fd858..88aed60c 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -209,7 +209,7 @@ Assuming you want to include `CustomPulseTrain-SendCustomWaveform.bonsai`: ::: ``` -Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule and requires the `build.ps1`(./documentation-docfx.md#docfx-folder-organization) file and a [local bonsai environment](./documentation-docfx.md#repository-organization). +Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule and requires the [build.ps1](./documentation-docfx.md#docfx-folder-organization) file and a [local bonsai environment](./documentation-docfx.md#repository-organization). To generate the images locally for the `docfx` local preview, navigate to the `docs` folder and run this command (make sure `build.ps1` has been modified to point to the package src): From 5bb3b85bae057485f9fa810a5f1dde1f35037f34 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 8 Nov 2024 17:51:35 -0800 Subject: [PATCH 25/35] Apply suggestions from code review Co-authored-by: glopesdev --- README.md | 10 +++--- articles/create-package.md | 2 +- articles/documentation-docfx.md | 48 +++++++++++++-------------- articles/documentation-style-guide.md | 30 ++++++++--------- 4 files changed, 45 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index e937ca60..e9160867 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ This repo contains the technical reference manual for the Bonsai visual programming language, in addition to articles and examples that document the collective knowledge of the Bonsai user community. > [!NOTE] -> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. +> This repo hosts the documentation for packages in the Bonsai standard library. Documentation for other Bonsai packages is hosted from each package repo. -Documentation is built using `docfx`, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages. +Documentation is built using `docfx`, a static site generator that automatically generates API documentation for .NET projects, and deployed using GitHub Actions on GitHub Pages. We welcome all contributions! For more information please refer to our [Contribution Guide](https://bonsai-rx.org/contribute/). @@ -22,8 +22,8 @@ These instructions apply to repos that already have a docfx website created. ```powershell dotnet tool restore ``` -5. In a Windows Powershell, use the command `dotnet docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes. -6. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. -7. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. +5. From a terminal window, use the command `dotnet docfx --serve` to generate a local preview of the documentation website as you are making changes. +6. When you are ready to have your contribution reviewed, commit your edits to the appropriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. +7. Community maintainers will be assigned to review the PR and will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. For more info, check out the [Documentation with docfx](https://bonsai-rx.org/docs/articles/documentation-docfx.html) and [Documentation Style Guide](https://bonsai-rx.org/docs/articles/documentation-style-guide.html) articles. diff --git a/articles/create-package.md b/articles/create-package.md index dc543754..aee21b22 100644 --- a/articles/create-package.md +++ b/articles/create-package.md @@ -98,7 +98,7 @@ The Bonsai language can be extended with custom packages, which are installed an > [!TIP] > Use [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) to document your code. -> Check out the [Documentation with docfx](./documentation-docfx.md) article for information on how to use [docfx](https://dotnet.github.io/docfx/index.html) to automatically generate documentation for your package online. +> Check out the [Documentation with docfx](./documentation-docfx.md) article for information on how to use [docfx](https://dotnet.github.io/docfx/index.html) to automatically generate documentation pages for your package. ## Publishing a package project diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index e538146e..4e2fbe79 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -2,18 +2,18 @@ Effective online documentation plays a crucial role in driving the adoption and usage of custom packages. For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to facilitate key Bonsai features, we encourage package developers to use `docfx` for consistency and support within the Bonsai Ecosystem. -The following article will go into how to create a `docfx` website for your package. For documentation style guidelines, check out the [Documentation Style Guide](./documentation-style-guide.md). +The following article will go into detail on how to create a `docfx` website for your package. For documentation style guidelines, check out the [Documentation Style Guide](./documentation-style-guide.md). > [!TIP] > We recommend using a code editor with an integrated terminal like [Visual Studio Code](https://code.visualstudio.com/) to follow along with these instructions. ## Repository organization -For effective long term maintenance of documentation across different repositories, package repositories should be organised according to this standardized folder structure before setting up `docfx`: +For effective long term maintenance of documentation, package repositories should be organized according to the following standard folder structure before setting up `docfx`: ``` . ├── .bonsai/ # Local Bonsai Environment (see note below) -├── .github/workflows/ # Github Actions Folder (see note below) +├── .github/workflows/ # GitHub Actions Folder (see note below) │ └── docs.yml ├── docs/ # Folder to setup docfx └── src/ @@ -21,14 +21,14 @@ For effective long term maintenance of documentation across different repositori ... ``` -- `.bonsai/` - A local Bonsai [environment](https://bonsai-rx.org/docs/articles/environments.html) is required for a script that exports Bonsai workflow images. To create one run these following commands: +- `.bonsai/` - A local Bonsai [environment](https://bonsai-rx.org/docs/articles/environments.html) is required to run the script that exports Bonsai workflow images. To create one, run the following commands: ```powershell dotnet new install Bonsai.Templates dotnet new bonsaienv ``` -- `.github/workflows/` - The docfx website is published to [Github Pages](https://pages.github.com/) using a [Github Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow called `docs.yml`. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend `Bonsai.PackageName` to point to your package source code in `docs.yml`. +- `.github/workflows/` - The docfx website is published to [GitHub Pages](https://pages.github.com/) using a [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow called `docs.yml`. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend `Bonsai.PackageName` to point to your package source code in `docs.yml`. ## Setting up docfx @@ -59,12 +59,12 @@ Enable PDF? [y/n] (y): n Congrats! You now have a minimal `docfx` website. Run the following command to generate a local preview of the website, and verify that API documentation for your package has been generated successfully: ```powershell -dotnet docfx docfx.json --serve +dotnet docfx --serve ``` ### Docfx folder organization -Before proceeding further into configuring the `docfx` website, the `docs` folder should be organised according to this layout for effective long term maintenance. +Before proceeding further into configuring the `docfx` website, the `docs` folder should be organized according to the following layout to facilitate long term maintenance. ``` . @@ -78,14 +78,14 @@ Before proceeding further into configuring the `docfx` website, the `docs` folde │ ├── main.css │ └── main.js ├── tutorial/ # Place "Tutorials" section articles here (see style guide) -├── workflow/ # Place .bonsai workflow files here for image export +├── workflows/ # Place .bonsai workflow files here for image export ├── build.ps1 # Bonsai workflow image export script (see note below) ├── logo.svg # Website logo └── favicon.ico # Website bookmark logo ... ``` -- `bonsai/` - this folder is where we place a submodule that we have created called [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from `Bonsai` workflows (if you want to include them in your article) and adds a CSS template for `Bonsai` workflow containers (these containers allow users to easily copy workflows into the `Bonsai` editor). To add it, run this command in the `docs` folder: +- `bonsai/` - this folder is where we initialize the submodule referencing [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from `Bonsai` workflows (if you want to include them in your article) and adds a CSS template for `Bonsai` workflow containers (these containers allow users to easily copy workflows into the `Bonsai` editor). To create this submodule, run this command in the `docs` folder: ```powershell git submodule add https://github.com/bonsai-rx/docfx-tools bonsai @@ -110,7 +110,7 @@ git submodule update --remote ### Configuring docfx -The `docfx.json` file in the `docs` folder hosts the configuration options for the website and needs to be modified to fully utilize the features availiable. If in doubt, refer to a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) or the [docfx documentation](https://dotnet.github.io/docfx/) for more information. These steps are listed in order of appearance in `docfx.json`. +The `docfx.json` file in the `docs` folder hosts the configuration options for the website and needs to be modified to fully utilize the available features. If in doubt, refer to a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) or the [docfx documentation](https://dotnet.github.io/docfx/) for more information. These steps are listed in order of appearance in `docfx.json`. 1) Add a `filter` attribute to [filter](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) obsolete operators in the package. In the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. @@ -131,7 +131,7 @@ apiRules: uid: System.ObsoleteAttribute ``` -2) Exclude these files from being included in the building of content to avoid duplicate errors. +2) Exclude these files from content to avoid duplicate errors. ```json "build": { @@ -220,22 +220,22 @@ apiRules: } ``` -## Publishing to Github Pages +## Publishing to GitHub Pages -Once you are satisfied with the website, publish to [Github Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site). A Github Actions workflow has already been created, make sure `docs.yml` is in the `.github/workflows` [folder](#repository-organization). +Once you are satisfied with the website, publish to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site). A GitHub Actions workflow should already be in place if you follow the standard folder structure. Make sure `docs.yml` is in the `.github/workflows` [folder](#repository-organization). 1) Setup a new branch called `gh-pages` on your fork of the repository. -2) Go to your repo settings -> `Pages` -> `Build and deployment` - under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. +2) Go to your repo settings > `Pages` > `Build and deployment` > under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. 3) Commit your edits and push them online. -4) Under the `Actions` tab of your github repo, trigger the `Build docs` workflow manually with the `Run workflow` button on the branch you commited your edits to. This will build the docs site on the `gh-pages` branch. +4) Under the `Actions` tab of your GitHub repo, trigger the `Build docs` workflow manually with the `Run workflow` button on the branch you committed your edits to. This will build the docs site on the `gh-pages` branch. 5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. -7) The URL for the site can be found in your `Pages` section of your repository settings. +7) The URL for the site can be found in the `Pages` section of your repository settings. > [!NOTE] -> To ensure that the Bonsai Editor can link to the `Reference` documentation for operators, make sure that the `PackageProjectURL` in either the `.csproj` file or the `Directory.Build.props` file points to the URL for the documentation website. +> To ensure that the Bonsai Editor can link to the reference documentation for package operators, make sure that the `PackageProjectUrl` in either the `.csproj` file or the `Directory.Build.props` file points to the URL for the documentation website. ## Version control cleanup -To keep your online Github repository clean, you can use .gitignore files to ignore files that are generated for documentation that do not need to be version controlled. Add each item as a separate line to the appropriate .gitignore file in each location. +To keep your online GitHub repository clean, you can use `.gitignore` files to ignore files or documentation which are automatically generated and do not need to be version controlled. Add each item as a separate line to the appropriate `.gitignore` file in each location. ``` . @@ -252,9 +252,9 @@ To keep your online Github repository clean, you can use .gitignore files to ign ## Testing unpublished packages -To write documentation for [new packages or releases](https://bonsai-rx.org/docs/articles/create-package.html) that have not been published to the community, test them in Visual Studio. +To write documentation for [new packages or releases](https://bonsai-rx.org/docs/articles/create-package.html) that have not yet been published to the community, it is good practice to start by writing test workflows in Visual Studio. -1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free). +1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free for open-source projects). 2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. 3) In Visual Studio, open `src/PackageName.sln` in the repository. 4) Press F5 to open the Bonsai editor with the new package added. @@ -269,10 +269,10 @@ These are usually due to folders not being in the right place, check the directo ### Docfx local preview not updating -If you are running the local preview `dotnet docfx docfx.json --serve` and not seeing changes: +If you are running the local preview `dotnet docfx --serve` and not seeing changes: 1) Make sure that any changes you have made in your code editor are saved. -2) Hard refresh pages in the browser using either Ctrl+Shift+R and Ctrl+F5 or clear the cache to avoid cache issues. +2) Hard refresh pages in the browser using either `Ctrl`+`Shift`+`R` and `Ctrl`+`F5` or clear the cache to avoid cache issues. 3) As a last resort - check that the content updates online by [publishing your website](#publishing-to-github-pages). ### Differences between local and online builds @@ -281,12 +281,12 @@ If there are discrepancies between local and online builds and they persist, thi Make sure to run this command which uses the local installation of `docfx` ```powershell -dotnet docfx docfx.json --serve +dotnet docfx --serve ``` Instead of this command which uses the global installation of `docfx`. ```powershell -docfx docfx.json --serve +docfx --serve ``` The `.config` folder in the root directory contains `docfx` local version info if you need to check it. diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index 88aed60c..a5627321 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -1,12 +1,12 @@ # Documentation Style Guide -Clear, well-organized documentation helps users understand package functionality, integrate it into their workflows, and troubleshoot effectively. +Clear, well-organized documentation helps everyone understand package functionality, integrate it into their workflows, and troubleshoot effectively. Through our experience documenting Bonsai, we've established several best practices for presenting information, which are outlined here alongside practical methods for implementation in [docfx](./documentation-docfx.md). This document is intended as a living resource, open to feedback and continuous improvement, rather than a static guide. Click on the `Edit this page` button or raise an issue on the [bonsai-docs](https://github.com/bonsai-rx/docs/issues) repository if you have a suggestion. ## Article organization -In general, we have found that three types of articles, organized into distinct website sections, are sufficient to address the needs of most users and their learning styles. +In general, we have converged on three types of articles, organized into distinct website sections, to address the needs of most people and their different learning styles. * Manual - hosts documentation that explains the basic workflow of the package or functions of the various operators. * Reference - hosts technical documentation for each operator, generated automatically by DocFX from XML comments in source code or supplemented with individual operator articles. @@ -14,7 +14,7 @@ In general, we have found that three types of articles, organized into distinct To construct these 3 sections: -1) Ensure that the `docs` folder has a `articles` and `tutorials` folder. The `api` folder is automatically generated. +1) Ensure that the `docs` folder has an `articles` and `tutorials` folder. The `api` folder is automatically generated. 2) For the navigation bar at the top of the website, edit the `docs/toc.yml` file to reflect the location and name of the various folders. ```yml @@ -58,16 +58,16 @@ Here is a same `toc.yml` but this time with a nested table of content layout (ar For the `Manual` section we typically see these elements: - Getting Started/Landing page - This typically includes a description of what the package does, how to install the package and funding/acknowledgements. This belongs in `docs/index.md`. -- Installation Instructions - If a package requires external dependencies or additional configuration it would be helpful to dedicate an extra page to this. +- Installation Instructions - If a package requires external dependencies or additional configuration it can be helpful to dedicate an extra page to this. - Workflow/Conceptual Overview - Best illustrated with a flowchart or a basic workflow container. -Beyond that, there are many possible ways to organise the rest of the manual articles depending on the type of package that is being supported. +Beyond that, there are many possible ways to organize the rest of the manual articles depending on the type of package that is being described. #### Individual operator articles One approach that we recommend is to try and write articles for each individual operator. This approach has several advantages: -- individual operator articles can be integrated into the automatically generated `Reference` documentation using docfx's `overwrite` function, allowing for supplemental content like images and workflows. +- Individual operator articles can be integrated into the automatically generated `Reference` documentation using docfx's `overwrite` function, allowing for supplemental content like images and workflows. - These articles can also be combined into larger conceptual `Manual` articles, providing organizational flexibility. - Writing individual operator articles ensures complete coverage of all operators. @@ -94,16 +94,16 @@ Other ### Reference section -As mentioned the `Reference` section of the website is auto-generated from [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) in the code. A unique feature we have integrated into the Bonsai Editor is that when users when users right click on individual operators they will be shown the `Reference` page for that operator. For many users, this might be the most obvious entry point to the package documentation. Thus it is essential that developers ensure that: +As mentioned the `Reference` section of the website is auto-generated from [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) in the code. We have integrated into the Bonsai Editor the ability to right-click on individual operators and select `View Help`. This will bring up and load the `Reference` page for that operator in the editor itself. For most people, this might be the most obvious entry point to the package documentation. Thus it is essential that developers ensure that: 1) XML documentation comments are clear, simple and helpful. 2) Where appropriate, supplement additional information (basic workflow, images, long-form content) with an individual operator article using the `overwrite` function detailed in the previous section. -At present, we understand that the default template for the `Reference` page is a little too technically oriented, and somewhat confusing for Bonsai users to navigate. We are in the midst of revamping the template to cater to a broader audience and will update this section when it becomes availiable. +At present, we understand that the default template for the `Reference` page is a little too technical, and somewhat confusing to navigate. We are in the midst of revamping the template to cater to a broader audience and will update this section when it becomes available. ### Tutorials section -For the tutorials section, we suggest creating individual pages for various applications where the package is likely to be used. For each application, guide learners through the workflow step by step, organizing it into separate exercises with clear objectives and visible results. This structure makes the content more accessible and manageable for learners, especially for complex workflows. +For the tutorials section, we suggest creating individual pages for various applications where the package is likely to be used. For each application, try to guide learners through the workflow step by step, organizing it into separate exercises with clear objectives and visible results. This structure makes the content more accessible and manageable, especially for complex workflows. #### Submodule For packages with extensive tutorials, multimedia and other large files, a separate repository can be created and imported as a submodule. @@ -111,7 +111,7 @@ For packages with extensive tutorials, multimedia and other large files, a separ A tutorial submodule can be added with the following command in the `docs` directory: ```powershell -git submodule add https://github.com/bonsai-rx/machinelearning-examples +git submodule add https://github.com/bonsai-rx/package-examples ``` In addition, the `docfx.json` file needs to be modified to import the relevant resources. For an example of how to setup a Tutorial submodule, refer to the [Bonsai Machine Learning Package](https://github.com/bonsai-rx/machinelearning) package and its submodule [Machine Learning Examples](https://github.com/bonsai-rx/machinelearning-examples). @@ -122,11 +122,11 @@ In docfx, articles are written in [Markdown](https://dotnet.github.io/docfx/docs When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: -- Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation) +- Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation). - Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. - Use the imperative style i.e. "Link hardware triggers" rather than "Linking hardware triggers". -### Linking content +### Content links When linking to content (either images, or other articles, or workflow containers) use relative paths in this format: **Example:** @@ -145,7 +145,7 @@ For content in a different folder, use `../` to navigate up to the parent folder ### Cross-references and highlights -When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist that could be linked if it would be helpful and to avoid duplication. Link resources like websites for external libraries for users to explore for more information. +When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist that could be linked if it would be helpful and to avoid duplication. Link resources like websites for external libraries which may be useful to explore for more information. **Example:** @@ -196,7 +196,7 @@ You can also link to operators in other packages if their [xrefmap](./documentat ### Bonsai workflows -To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName-workflowName`. +To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName-workflowName.bonsai`. Add the `.bonsai` file to the `workflows` folder in the repository. In the text of the article that includes/references this example workflow, add a workflow container. **Example:** @@ -209,7 +209,7 @@ Assuming you want to include `CustomPulseTrain-SendCustomWaveform.bonsai`: ::: ``` -Workflow images are automatically exported as SVGs by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule and requires the [build.ps1](./documentation-docfx.md#docfx-folder-organization) file and a [local bonsai environment](./documentation-docfx.md#repository-organization). +Workflow images are automatically exported as SVG files by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule and requires the [build.ps1](./documentation-docfx.md#docfx-folder-organization) file and a [local bonsai environment](./documentation-docfx.md#repository-organization). To generate the images locally for the `docfx` local preview, navigate to the `docs` folder and run this command (make sure `build.ps1` has been modified to point to the package src): From 83c57d42e0712b1b19eaaa038ea08b60dd29dd26 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 8 Nov 2024 18:22:16 -0800 Subject: [PATCH 26/35] Further edits to spelling and formatting based on code review --- README.md | 2 +- articles/documentation-docfx.md | 18 +++++++++--------- articles/documentation-style-guide.md | 8 ++++---- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index e9160867..9bc38041 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ We welcome all contributions! For more information please refer to our [Contribu # Quick start guide for contributing to documentation -These instructions apply to repos that already have a docfx website created. +These instructions apply to repos that already have a `docfx` website created. 1. Fork the repository you want to contribute documentation to. 2. Ensure that you are working off the `main` branch in your fork and create a descriptively named branch for each article/issue that you want to work on. diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 4e2fbe79..99d47e0b 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -28,7 +28,7 @@ dotnet new install Bonsai.Templates dotnet new bonsaienv ``` -- `.github/workflows/` - The docfx website is published to [GitHub Pages](https://pages.github.com/) using a [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow called `docs.yml`. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend `Bonsai.PackageName` to point to your package source code in `docs.yml`. +- `.github/workflows/` - The `docfx` website is published to [GitHub Pages](https://pages.github.com/) using a [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow called `docs.yml`. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend `Bonsai.PackageName` to point to your package source code in `docs.yml`. ## Setting up docfx @@ -39,7 +39,7 @@ dotnet new tool-manifest dotnet tool install --local docfx ``` -2) Navigate to the `docs` folder and initialise a new docfx website with the following command. +2) Navigate to the `docs` folder and initialize a new `docfx` website with the following command. ```powershell dotnet docfx init @@ -101,9 +101,9 @@ To update the submodule to the latest commit: git submodule update --remote ``` -- `template/` - this custom CSS template patches in docfx-tools and adds a github link to the top right of the navigation bar. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the github link in `main.css` to your repository. +- `template/` - this custom CSS template patches in `docfx-tools` and adds a GitHub link to the top right of the navigation bar. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the GitHub link in `main.css` to your repository. -- `build.ps1` - this custom script exports Bonsai workflow images using `docfx-tools` and then calls the docfx build process. Download the file from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the line that specifies the package name and source location. +- `build.ps1` - this custom script exports Bonsai workflow images using `docfx-tools` and then calls the `docfx` build process. Download the file from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the line that specifies the package name and source location. - `logo.svg` and `favicon.ico` - for official Bonsai packages these can be downloaded from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository. @@ -145,7 +145,7 @@ apiRules: } ``` -3) Add the `overwrite` attribute to enable [individual operator articles](./documentation-style-guide.md) stored in the `apidocs` folder to be included in articles and API docs. +3) Add the `overwrite` attribute to enable [individual operator articles](./documentation-style-guide.md) stored in the `apidoc` folder to be included in articles and API docs. ```json "build": { @@ -197,7 +197,7 @@ apiRules: } ``` -7) Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(DocFX markdown processor) extensions for additional markdown functionality. +7) Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(docfx markdown processor) extensions for additional markdown functionality. ```json "build": { @@ -210,7 +210,7 @@ apiRules: } ``` -8) Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with docfx documentation, add their `xrefmap.yml` here as well. +8) Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with `docfx` documentation, add their `xrefmap.yml` here as well. ```json "build": { @@ -277,7 +277,7 @@ If you are running the local preview `dotnet docfx --serve` and not seeing chang ### Differences between local and online builds -If there are discrepancies between local and online builds and they persist, this could indicate a docfx version conflict. The online build process uses a local installation of `docfx` but it is also possible to install `docfx` globally (which we do not recommend). To check if this is the cause of the discrepancy: +If there are discrepancies between local and online builds and they persist, this could indicate a `docfx` version conflict. The online build process uses a local installation of `docfx` but it is also possible to install `docfx` globally (which we do not recommend). To check if this is the cause of the discrepancy: Make sure to run this command which uses the local installation of `docfx` ```powershell @@ -290,7 +290,7 @@ docfx --serve ``` The `.config` folder in the root directory contains `docfx` local version info if you need to check it. -If you wish to update the local installation of docfx run this command in the root directory: +If you wish to update the local installation of `docfx` run this command in the root directory: ```powershell dotnet tool update docfx diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index a5627321..a8da2a6a 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -9,7 +9,7 @@ Through our experience documenting Bonsai, we've established several best practi In general, we have converged on three types of articles, organized into distinct website sections, to address the needs of most people and their different learning styles. * Manual - hosts documentation that explains the basic workflow of the package or functions of the various operators. -* Reference - hosts technical documentation for each operator, generated automatically by DocFX from XML comments in source code or supplemented with individual operator articles. +* Reference - hosts technical documentation for each operator, generated automatically by `docfx` from XML comments in source code or supplemented with individual operator articles. * Tutorials - hosts examples or tutorials for various applications. This section is optional, but valuable for more complicated applications or packages which require operators from other packages for their execution. To construct these 3 sections: @@ -67,7 +67,7 @@ Beyond that, there are many possible ways to organize the rest of the manual art One approach that we recommend is to try and write articles for each individual operator. This approach has several advantages: -- Individual operator articles can be integrated into the automatically generated `Reference` documentation using docfx's `overwrite` function, allowing for supplemental content like images and workflows. +- Individual operator articles can be integrated into the automatically generated `Reference` documentation by using the `overwrite` feature in `docfx`, allowing for supplemental content like images and workflows. - These articles can also be combined into larger conceptual `Manual` articles, providing organizational flexibility. - Writing individual operator articles ensures complete coverage of all operators. @@ -118,7 +118,7 @@ In addition, the `docfx.json` file needs to be modified to import the relevant r ## Article formatting guide -In docfx, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine. Refer to these links for more information on how to format content in markdown. +In `docfx`, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine. Refer to these links for more information on how to format content in markdown. When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: @@ -175,7 +175,7 @@ Highlight folders, filenames, package names, functions, actions, editor/website ### Standard formatting for operators and operator properties -When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). +When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in docfx](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. From 10d4a8ea86debb86129a85559edcdefc88386c9e Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 8 Nov 2024 20:45:32 -0800 Subject: [PATCH 27/35] Edit README to add contribution section and clarify external links --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9bc38041..1ddb26e2 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,11 @@ This repo contains the technical reference manual for the Bonsai visual programm Documentation is built using `docfx`, a static site generator that automatically generates API documentation for .NET projects, and deployed using GitHub Actions on GitHub Pages. -We welcome all contributions! For more information please refer to our [Contribution Guide](https://bonsai-rx.org/contribute/). +# Contributing + +Bonsai is a programming language with a growing community of users and developers. Anyone is welcome to participate by reporting bugs, proposing features or improvements, or contributing pull requests directly to our open-source repositories. + +For more information please see our [Contributor Guide](https://bonsai-rx.org/contribute/). By contributing to our project, we also expect you to uphold our community [Code of Conduct](https://bonsai-rx.org/code-of-conduct). # Quick start guide for contributing to documentation @@ -18,12 +22,15 @@ These instructions apply to repos that already have a `docfx` website created. 1. Fork the repository you want to contribute documentation to. 2. Ensure that you are working off the `main` branch in your fork and create a descriptively named branch for each article/issue that you want to work on. 3. Download and install dotnet (https://dotnet.microsoft.com/en-us/download) -4. Restore `docfx` by running +4. From a terminal window, restore `docfx` by running: ```powershell dotnet tool restore ``` -5. From a terminal window, use the command `dotnet docfx --serve` to generate a local preview of the documentation website as you are making changes. +5. Navigate to the directory where the file `docfx.json`is located and run the following command to generate a local preview of the documentation website as you are making changes. +```powershell +dotnet docfx --serve +``` 6. When you are ready to have your contribution reviewed, commit your edits to the appropriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo. 7. Community maintainers will be assigned to review the PR and will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published. -For more info, check out the [Documentation with docfx](https://bonsai-rx.org/docs/articles/documentation-docfx.html) and [Documentation Style Guide](https://bonsai-rx.org/docs/articles/documentation-style-guide.html) articles. +Check out the [Documentation Style Guide](https://bonsai-rx.org/docs/articles/documentation-style-guide.html) for content formatting tips and the [Documentation With Docfx](https://bonsai-rx.org/docs/articles/documentation-docfx.html) article if you need help with `docfx`. \ No newline at end of file From 2567ef1b78ba9feb929b88e743334bff1eb6b6dd Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Tue, 12 Nov 2024 12:28:31 -0800 Subject: [PATCH 28/35] Apply suggestions to change absolute to relative links Co-authored-by: glopesdev --- articles/documentation-docfx.md | 6 +++--- articles/documentation-style-guide.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 99d47e0b..9c1e2c89 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -21,7 +21,7 @@ For effective long term maintenance of documentation, package repositories shoul ... ``` -- `.bonsai/` - A local Bonsai [environment](https://bonsai-rx.org/docs/articles/environments.html) is required to run the script that exports Bonsai workflow images. To create one, run the following commands: +- `.bonsai/` - A local Bonsai [environment](./environments.md) is required to run the script that exports Bonsai workflow images. To create one, run the following commands: ```powershell dotnet new install Bonsai.Templates @@ -252,12 +252,12 @@ To keep your online GitHub repository clean, you can use `.gitignore` files to i ## Testing unpublished packages -To write documentation for [new packages or releases](https://bonsai-rx.org/docs/articles/create-package.html) that have not yet been published to the community, it is good practice to start by writing test workflows in Visual Studio. +To write documentation for [new packages or releases](./create-package.md) that have not yet been published to the community, it is good practice to start by writing test workflows in Visual Studio. 1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free for open-source projects). 2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. 3) In Visual Studio, open `src/PackageName.sln` in the repository. -4) Press F5 to open the Bonsai editor with the new package added. +4) Press F5 to open the Bonsai editor with the new package added. 5) From here, you can make Bonsai workflows and save them as per normal. diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index a8da2a6a..8968dfca 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -145,7 +145,7 @@ For content in a different folder, use `../` to navigate up to the parent folder ### Cross-references and highlights -When working on an article, first check [the main documentation](https://bonsai-rx.org/docs/) to see what written material might already exist that could be linked if it would be helpful and to avoid duplication. Link resources like websites for external libraries which may be useful to explore for more information. +When working on an article, first check [the main documentation](../index.md) and confirm whether written material already exists that could be linked to avoid duplication. Also include links to resources like websites for external libraries which may be useful to explore for more information. **Example:** From fb42b2c7182fcce0daa38b0b8a86d2940c5c459d Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Tue, 12 Nov 2024 12:44:16 -0800 Subject: [PATCH 29/35] Change absolute links to relative links in remaining articles --- articles/create-package.md | 2 +- tutorials/closed-loop.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/create-package.md b/articles/create-package.md index aee21b22..763bfa7f 100644 --- a/articles/create-package.md +++ b/articles/create-package.md @@ -113,7 +113,7 @@ The Bonsai language can be extended with custom packages, which are installed an 3. Build the project in **Release** mode. If all metadata is correctly specified, the build process should generate a `.nupkg` file as part of the output. By default, it will be placed in the same `bin\Release` folder where the project assembly (.dll) is generated. -4. To install the package in the editor, [configure a new package source](https://bonsai-rx.org/docs/articles/packages.html#configure-package-sources) pointing to a folder containing your generated `.nupkg` file, or simply copy the `.nupkg` file to the `Gallery` folder of your local Bonsai installation. The package should then be listed in the package manager (make sure to select the package source where the package is located if you cannot find it in the list). +4. To install the package in the editor, [configure a new package source](./packages.md#configure-package-sources) pointing to a folder containing your generated `.nupkg` file, or simply copy the `.nupkg` file to the `Gallery` folder of your local Bonsai installation. The package should then be listed in the package manager (make sure to select the package source where the package is located if you cannot find it in the list). > [!Warning] > If you have your custom package installed in the same editor used to debug the source code, Bonsai will prefer the installed package over the compiled source code library. In this case, either uninstall the package, or use a local Bonsai installation. diff --git a/tutorials/closed-loop.md b/tutorials/closed-loop.md index 2facbb5a..1e191633 100644 --- a/tutorials/closed-loop.md +++ b/tutorials/closed-loop.md @@ -178,7 +178,7 @@ def process(value): - In a new branch, create a video tracking pipeline using `ConvertColor`, `HsvThreshold`, and the `Centroid` operator to directly compute the centre of mass of a colored object. - Insert a `Negate` transform. This will make the X and Y coordinates of the centroid negative. -We now want to map our negative centroid to the `Translation` property of `AffineTransform`, so that we dynamically translate each frame using the negative position of the object. You can do this by using [property mapping operators](http://bonsai-rx.org/docs/property-mapping){:target="\_blank"}. +We now want to map our negative centroid to the `Translation` property of `AffineTransform`, so that we dynamically translate each frame using the negative position of the object. You can do this by using [property mapping operators](../articles/property-mapping.md). - Insert an `InputMapping` operator. - Connect the `InputMapping` to the `AffineTransform` operator. From 4457090674e24c604224bd663fda5dc14194e59d Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 15 Nov 2024 16:53:51 +0000 Subject: [PATCH 30/35] Minor edits to wording clarity and formatting --- articles/documentation-docfx.md | 23 ++++++++----------- articles/documentation-style-guide.md | 33 ++++++++++++--------------- 2 files changed, 25 insertions(+), 31 deletions(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 9c1e2c89..5b5e9839 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -1,6 +1,6 @@ # Documentation With Docfx -Effective online documentation plays a crucial role in driving the adoption and usage of custom packages. For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation online. As we have integrated and extended `docfx` to facilitate key Bonsai features, we encourage package developers to use `docfx` for consistency and support within the Bonsai Ecosystem. +Documentation plays a crucial role in helping everyone adopt and use custom packages. For packages published by the Bonsai Foundation, we use [docfx](https://dotnet.github.io/docfx/index.html), a static site generator for .NET projects, to automatically generate and publish documentation pages. As we have integrated and extended `docfx` with specific Bonsai documentation features, we encourage package developers to use `docfx` to ensure a consistent and integrated experience across the Bonsai community. The following article will go into detail on how to create a `docfx` website for your package. For documentation style guidelines, check out the [Documentation Style Guide](./documentation-style-guide.md). @@ -8,7 +8,7 @@ The following article will go into detail on how to create a `docfx` website for > We recommend using a code editor with an integrated terminal like [Visual Studio Code](https://code.visualstudio.com/) to follow along with these instructions. ## Repository organization -For effective long term maintenance of documentation, package repositories should be organized according to the following standard folder structure before setting up `docfx`: +To help long term maintenance of documentation, we recommend package repositories to be organized according to the following standard folder structure before setting up `docfx`: ``` . @@ -18,7 +18,7 @@ For effective long term maintenance of documentation, package repositories shoul ├── docs/ # Folder to setup docfx └── src/ └── Bonsai.PackageName/ # Project files here -... +... ``` - `.bonsai/` - A local Bonsai [environment](./environments.md) is required to run the script that exports Bonsai workflow images. To create one, run the following commands: @@ -35,14 +35,14 @@ dotnet new bonsaienv 1) Setup a local installation of `docfx` in your package repository with the following commands (executed in the root directory): ```powershell -dotnet new tool-manifest -dotnet tool install --local docfx +dotnet new tool-manifest +dotnet tool install --local docfx ``` 2) Navigate to the `docs` folder and initialize a new `docfx` website with the following command. ```powershell -dotnet docfx init +dotnet docfx init ``` 3) Select these options for the new website. @@ -56,7 +56,7 @@ Enable site search? [y/n] (y): y Enable PDF? [y/n] (y): n ``` -Congrats! You now have a minimal `docfx` website. Run the following command to generate a local preview of the website, and verify that API documentation for your package has been generated successfully: +You should now have a minimal `docfx` website. Run the following command to generate a local preview of the website, and verify that API documentation for your package has been generated successfully: ```powershell dotnet docfx --serve @@ -64,7 +64,7 @@ dotnet docfx --serve ### Docfx folder organization -Before proceeding further into configuring the `docfx` website, the `docs` folder should be organized according to the following layout to facilitate long term maintenance. +The documentation guides assume the `docs` folder is organized according to the following layout: ``` . @@ -77,8 +77,8 @@ Before proceeding further into configuring the `docfx` website, the `docs` folde │ └── public/ │ ├── main.css │ └── main.js -├── tutorial/ # Place "Tutorials" section articles here (see style guide) -├── workflows/ # Place .bonsai workflow files here for image export +├── tutorials/ # Place "Tutorials" section articles here (see style guide) +├── workflows/ # Place .bonsai workflow files here for image export ├── build.ps1 # Bonsai workflow image export script (see note below) ├── logo.svg # Website logo └── favicon.ico # Website bookmark logo @@ -295,6 +295,3 @@ If you wish to update the local installation of `docfx` run this command in the ```powershell dotnet tool update docfx ``` - - - diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index 8968dfca..b3b0c11c 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -1,8 +1,6 @@ # Documentation Style Guide -Clear, well-organized documentation helps everyone understand package functionality, integrate it into their workflows, and troubleshoot effectively. - -Through our experience documenting Bonsai, we've established several best practices for presenting information, which are outlined here alongside practical methods for implementation in [docfx](./documentation-docfx.md). This document is intended as a living resource, open to feedback and continuous improvement, rather than a static guide. Click on the `Edit this page` button or raise an issue on the [bonsai-docs](https://github.com/bonsai-rx/docs/issues) repository if you have a suggestion. +Through our experience documenting Bonsai, we have established a set of recommended practices for presenting information, which are outlined here alongside practical methods for implementation in [docfx](./documentation-docfx.md). This document is intended as a living resource, open to feedback and continuous improvement, rather than a static guide. Click on the `Edit this page` button or raise an issue on the [bonsai-docs](https://github.com/bonsai-rx/docs/issues) repository if you have a suggestion. ## Article organization @@ -12,7 +10,7 @@ In general, we have converged on three types of articles, organized into distinc * Reference - hosts technical documentation for each operator, generated automatically by `docfx` from XML comments in source code or supplemented with individual operator articles. * Tutorials - hosts examples or tutorials for various applications. This section is optional, but valuable for more complicated applications or packages which require operators from other packages for their execution. -To construct these 3 sections: +To construct these sections: 1) Ensure that the `docs` folder has an `articles` and `tutorials` folder. The `api` folder is automatically generated. 2) For the navigation bar at the top of the website, edit the `docs/toc.yml` file to reflect the location and name of the various folders. @@ -26,7 +24,7 @@ To construct these 3 sections: href: tutorials/ ``` 3) Add articles in markdown format to the `Manual` and `Tutorials` folder. -4) Add a toc.yml file to the `Manual` and `Tutorials` folder to generate the table of contents for that section. The `API` toc.yml is generated automatically. +4) Add a toc.yml file to the `Manual` and `Tutorials` folder to generate the table of contents for that section. The `Reference` toc.yml is generated automatically. Here is a sample `articles/toc.yml` with a flattened table of content layout (all articles will be visible in the TOC). This works best for most websites which do not have a lot of articles. ```yml @@ -72,24 +70,25 @@ One approach that we recommend is to try and write articles for each individual - Writing individual operator articles ensures complete coverage of all operators. Creating an individual operator article requires some additional steps. -For example, to create an individual operator article for a `PredictPoses` operator that will be included in a "Network Inference" `Manual` article as well as in the automatically generated `Reference` doc: +For example, to create an individual operator article for a `Timer` operator to be included in a `Manual` article as well as in the automatically generated `Reference` docs: -1) Create the `Bonsai_Sleap_PredictPoses.md` article and place it in the `docs/apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the namespace.operator format. +1) Create the `Bonsai_Reactive_Timer.md` article and place it in the `docs/apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the namespace.operator format. ```yml --- -uid: Bonsai.Sleap.PredictPoses +uid: Bonsai.Reactive.Timer --- Write content here. ``` -2) Create a `Network-Inference.md` article and place it in the `docs/articles` folder. In the markdown file, include a reference to the individual operator.md file. +1) Create a new article markdown file and place it in the `docs/articles` folder. In this markdown file, include a reference to the individual operator.md file. ```markdown -Other -[!include[Title](../apidoc/Bonsai_Sleap_PredictPoses.md)] +Some documentation content. + +[!include[Title](../apidoc/Bonsai_Reactive_Timer.md)] ``` -> [!NOTE] +> [!NOTE] > The title is optional. ### Reference section @@ -105,10 +104,10 @@ At present, we understand that the default template for the `Reference` page is For the tutorials section, we suggest creating individual pages for various applications where the package is likely to be used. For each application, try to guide learners through the workflow step by step, organizing it into separate exercises with clear objectives and visible results. This structure makes the content more accessible and manageable, especially for complex workflows. -#### Submodule +#### Submodules For packages with extensive tutorials, multimedia and other large files, a separate repository can be created and imported as a submodule. -A tutorial submodule can be added with the following command in the `docs` directory: +A tutorial or example submodule can be added with the following command in the `docs` directory: ```powershell git submodule add https://github.com/bonsai-rx/package-examples @@ -217,13 +216,11 @@ To generate the images locally for the `docfx` local preview, navigate to the `d ./build.ps1 ``` -If any of the nodes are greyed out in the generated SVG, then additional packages need to be installed in the local bonsai environment. - -Simply open `bonsai.exe` in the `.bonsai` folder, go to the package manager and install the package. +If any of the nodes are greyed out in the generated SVG, then additional packages need to be installed in the local bonsai environment by using the package manager in the local bootstrapper `Bonsai.exe`. ### Figures -> [!NOTE] +> [!NOTE] > Avoid images/screenshots when possible as they do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. To include a figure or image in an article: From 7bc3fe817d495d8908c47cdb5fbb161cfbd36428 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Wed, 27 Nov 2024 11:16:53 +0000 Subject: [PATCH 31/35] Edit wording and embed assets directly in the text --- articles/documentation-docfx.md | 105 +++++++++++++++++--------- articles/documentation-style-guide.md | 70 +++++++++-------- 2 files changed, 103 insertions(+), 72 deletions(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 5b5e9839..8e30bb46 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -28,24 +28,24 @@ dotnet new install Bonsai.Templates dotnet new bonsaienv ``` -- `.github/workflows/` - The `docfx` website is published to [GitHub Pages](https://pages.github.com/) using a [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow called `docs.yml`. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend `Bonsai.PackageName` to point to your package source code in `docs.yml`. +- `.github/workflows/` - The `docfx` website is often automatically published to [GitHub Pages](https://pages.github.com/) using a [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow specified in the `docs.yml` file. Unfortunately these workflows tend to be very project specific and we do not yet have a standardized pipeline. For a minimal example and inspiration you can check [the workflow for this repository](https://github.com/bonsai-rx/docs/blob/main/.github/workflows/build.yml). -## Setting up docfx +## Setup docfx -1) Setup a local installation of `docfx` in your package repository with the following commands (executed in the root directory): +You can setup a local installation of `docfx` directly in your package repository with the following commands (executed in the root directory): ```powershell dotnet new tool-manifest dotnet tool install --local docfx ``` -2) Navigate to the `docs` folder and initialize a new `docfx` website with the following command. +Then navigate to the `docs` folder and initialize a new `docfx` website with the following command: ```powershell dotnet docfx init ``` -3) Select these options for the new website. +We recommend the following options for new websites (make sure to match the name to your package): ```powershell Name (mysite): Bonsai - Package Name @@ -101,18 +101,46 @@ To update the submodule to the latest commit: git submodule update --remote ``` -- `template/` - this custom CSS template patches in `docfx-tools` and adds a GitHub link to the top right of the navigation bar. Download this folder from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the GitHub link in `main.css` to your repository. +- `template/` - the files in this `docfx` template extend the base template in `docfx-tools`. Below are templates for `main.css` and `main.js` which add a GitHub link to the top right of the navigation bar and include all styles for workflow containers. -- `build.ps1` - this custom script exports Bonsai workflow images using `docfx-tools` and then calls the `docfx` build process. Download the file from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository and amend the line that specifies the package name and source location. +###### main.css +```css +@import "workflow.css"; +``` + +###### main.js +```js +import WorkflowContainer from "./workflow.js" + +export default { + defaultTheme: 'auto', + iconLinks: [{ + icon: 'github', + href: 'https://github.com/org-name/PackageName', + title: 'GitHub' + }], + start: () => { + WorkflowContainer.init(); + } +} +``` + +- `build.ps1` - this custom script exports Bonsai workflow images using `docfx-tools` and then calls the `docfx` build process. Make sure to change the line to point to your package output location: + +```powershell +.\bonsai\modules\Export-Image.ps1 "..\src\Bonsai.PackageName\bin\Release\net462" +dotnet docfx @args +``` - `logo.svg` and `favicon.ico` - for official Bonsai packages these can be downloaded from the [docfx-assets](https://github.com/bonsai-rx/docfx-assets) repository. ### Configuring docfx -The `docfx.json` file in the `docs` folder hosts the configuration options for the website and needs to be modified to fully utilize the available features. If in doubt, refer to a Bonsai package repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) or the [docfx documentation](https://dotnet.github.io/docfx/) for more information. These steps are listed in order of appearance in `docfx.json`. +The `docfx.json` file in the `docs` folder specifies the configuration options for the website and needs to be modified to make use of all available features. If in doubt, refer to a Bonsai package repository that has been recently updated, e.g. [bonsai-rx/machinelearning](https://bonsai-rx.org/machinelearning/), or the [docfx documentation](https://dotnet.github.io/docfx/) for more information. These steps are listed in order of appearance in `docfx.json`. -1) Add a `filter` attribute to [filter](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) obsolete operators in the package. In the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. +#### Hide obsolete operators +Add a [`filter`](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) attribute to hide obsolete operators from the package docs. In the process of upgrading packages we want to avoid documenting operators that are no longer supported (but are still included for compatibility purposes for old workflows). You can also hide private classes that are not supposed to be shown to the end user. ```yml "metadata": [ @@ -122,7 +150,7 @@ The `docfx.json` file in the `docs` folder hosts the configuration options for t ] ``` -Make a file called `filter.yml` with the following lines and place in the `docs` directory. You can also specify other [uids](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) here. +Make a file called `filter.yml` with the following lines and place it in the `docs` directory. You can also specify other [uids](https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis) here. ```yml apiRules: @@ -131,7 +159,7 @@ apiRules: uid: System.ObsoleteAttribute ``` -2) Exclude these files from content to avoid duplicate errors. +Exclude these files from content to avoid duplicate errors. ```json "build": { @@ -145,7 +173,8 @@ apiRules: } ``` -3) Add the `overwrite` attribute to enable [individual operator articles](./documentation-style-guide.md) stored in the `apidoc` folder to be included in articles and API docs. +#### Enable operator articles +Add the `overwrite` attribute to ensure [individual operator articles](./documentation-style-guide.md) stored in the `apidoc` folder are included in both articles and API docs. ```json "build": { @@ -163,7 +192,8 @@ apiRules: } ``` -4) Modify the `resource` attribute to include files that need to be imported. +#### Add resource files +Modify the `resource` attribute to include files that need to be imported. ```json "resource": { @@ -176,7 +206,8 @@ apiRules: } ``` -5) Modify the `template` attribute to use the modern template and apply the `docfx-tools` custom templates to enable workflow containers. +#### Apply modern template +Modify the `template` attribute to use the modern template and apply the `docfx-tools` custom templates to enable workflow containers. ```json "template": [ @@ -187,7 +218,8 @@ apiRules: ] ``` -6) Modify the `globalMetadata` attribute to change package name and add the `_appFooter` attribute and description. +#### Update global metadata +Modify the `globalMetadata` attribute to change package name and add the `_appFooter` attribute and description. ```json "globalMetadata": { @@ -197,7 +229,8 @@ apiRules: } ``` -7) Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(docfx markdown processor) extensions for additional markdown functionality. +#### Enable custom extensions and xref +Add the `markdownEngineProperties` attribute to enable [markdig](https://github.com/xoofx/markdig)(docfx markdown processor) extensions for additional markdown functionality. ```json "build": { @@ -210,7 +243,7 @@ apiRules: } ``` -8) Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with `docfx` documentation, add their `xrefmap.yml` here as well. +Add the `xref` attribute to cross reference classes from the Bonsai library (if you use them to build your package). If you have used other libraries with `docfx` documentation, add their `xrefmap.yml` here as well. ```json "build": { @@ -224,12 +257,12 @@ apiRules: Once you are satisfied with the website, publish to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site). A GitHub Actions workflow should already be in place if you follow the standard folder structure. Make sure `docs.yml` is in the `.github/workflows` [folder](#repository-organization). -1) Setup a new branch called `gh-pages` on your fork of the repository. -2) Go to your repo settings > `Pages` > `Build and deployment` > under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. -3) Commit your edits and push them online. -4) Under the `Actions` tab of your GitHub repo, trigger the `Build docs` workflow manually with the `Run workflow` button on the branch you committed your edits to. This will build the docs site on the `gh-pages` branch. -5) Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. -7) The URL for the site can be found in the `Pages` section of your repository settings. +1. Setup a new branch called `gh-pages` on your fork of the repository. +2. Go to your repo settings > `Pages` > `Build and deployment` > under `Source` select `Deploy from a branch` and make sure `gh-pages` is selected. +3. Commit your edits and push them online. +4. Under the `Actions` tab of your GitHub repo, trigger the `Build docs` workflow manually with the `Run workflow` button on the branch you committed your edits to. This will build the docs site on the `gh-pages` branch. +5. Once the `Build docs` workflow has been completed, the `pages-build-deployment` workflow will run and publish your forked repo automatically. +7. The URL for the site can be found in the `Pages` section of your repository settings. > [!NOTE] > To ensure that the Bonsai Editor can link to the reference documentation for package operators, make sure that the `PackageProjectUrl` in either the `.csproj` file or the `Directory.Build.props` file points to the URL for the documentation website. @@ -250,32 +283,32 @@ To keep your online GitHub repository clean, you can use `.gitignore` files to i ... ``` -## Testing unpublished packages +## Creating example workflows To write documentation for [new packages or releases](./create-package.md) that have not yet been published to the community, it is good practice to start by writing test workflows in Visual Studio. -1) Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free for open-source projects). -2) Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. -3) In Visual Studio, open `src/PackageName.sln` in the repository. -4) Press F5 to open the Bonsai editor with the new package added. -5) From here, you can make Bonsai workflows and save them as per normal. +1. Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free for open-source projects). +2. Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. +3. In Visual Studio, open `src/PackageName.sln` in the repository. +4. Press F5 to open the Bonsai editor with the new package added. +5. From here, you can make Bonsai workflows and save them to the `workflows` folder as examples. ## Troubleshooting -### File not found errors +#### File not found errors -These are usually due to folders not being in the right place, check the directory trees above or a repository that has been recently updated (for instance https://bonsai-rx.org/machinelearning/) for reference. Also pay attention to any scripts/css files that require modification of the package name/link/source location. +These are usually due to folders not being in the right place. Check the directory trees above or a repository that has been recently updated, e.g. [bonsai-rx/machinelearning](https://bonsai-rx.org/machinelearning/), for reference. Also pay attention to any scripts or CSS files that require modification to the package name or link/source location. -### Docfx local preview not updating +#### Docfx local preview not updating If you are running the local preview `dotnet docfx --serve` and not seeing changes: -1) Make sure that any changes you have made in your code editor are saved. -2) Hard refresh pages in the browser using either `Ctrl`+`Shift`+`R` and `Ctrl`+`F5` or clear the cache to avoid cache issues. -3) As a last resort - check that the content updates online by [publishing your website](#publishing-to-github-pages). +1. Make sure that any changes you have made in your code editor are saved. +2. Hard refresh pages in the browser using either `Ctrl`+`Shift`+`R` and `Ctrl`+`F5` or clear the cache to avoid cache issues. +3. As a last resort - check that the content updates online by [publishing your website](#publishing-to-github-pages). -### Differences between local and online builds +#### Differences between local and online builds If there are discrepancies between local and online builds and they persist, this could indicate a `docfx` version conflict. The online build process uses a local installation of `docfx` but it is also possible to install `docfx` globally (which we do not recommend). To check if this is the cause of the discrepancy: diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index b3b0c11c..b84d055f 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -6,14 +6,14 @@ Through our experience documenting Bonsai, we have established a set of recommen In general, we have converged on three types of articles, organized into distinct website sections, to address the needs of most people and their different learning styles. -* Manual - hosts documentation that explains the basic workflow of the package or functions of the various operators. -* Reference - hosts technical documentation for each operator, generated automatically by `docfx` from XML comments in source code or supplemented with individual operator articles. -* Tutorials - hosts examples or tutorials for various applications. This section is optional, but valuable for more complicated applications or packages which require operators from other packages for their execution. +* `Manual` - articles explaining the core concepts of the package and functions of its various operators. +* `Reference` - technical documentation for each operator, generated automatically by `docfx` from XML comments in source code or supplemented with individual operator articles. +* `Tutorials` - examples or tutorials about using the package. This section is optional, but valuable for more complex applications or when packages interoperate deeply with other packages. To construct these sections: -1) Ensure that the `docs` folder has an `articles` and `tutorials` folder. The `api` folder is automatically generated. -2) For the navigation bar at the top of the website, edit the `docs/toc.yml` file to reflect the location and name of the various folders. +1. Ensure that the `docs` folder has an `articles` and `tutorials` folder. The `api` folder is automatically generated. +2. For the navigation bar at the top of the website, edit the `docs/toc.yml` file to reflect the location and name of the different folders. ```yml - name: Manual @@ -23,9 +23,9 @@ To construct these sections: - name: Tutorials href: tutorials/ ``` -3) Add articles in markdown format to the `Manual` and `Tutorials` folder. -4) Add a toc.yml file to the `Manual` and `Tutorials` folder to generate the table of contents for that section. The `Reference` toc.yml is generated automatically. -Here is a sample `articles/toc.yml` with a flattened table of content layout (all articles will be visible in the TOC). This works best for most websites which do not have a lot of articles. +3. Add articles in markdown format to the `Manual` and `Tutorials` folder. +4. Add a `toc.yml` file to the `Manual` and `Tutorials` folder to generate the table of contents for that section. The `toc.yml` for the `Reference` section is generated automatically. +Below is a sample `articles/toc.yml` with a flattened table of content layout (all articles will be visible in the TOC). This works best for websites which do not have a lot of articles. ```yml - href: ../index.md # Website Getting Started page that points to docs/index.md. Omit for tutorials/toc.yml @@ -40,7 +40,7 @@ Here is a sample `articles/toc.yml` with a flattened table of content layout (al > [!TIP] > Article filenames should be simple and reflect either the article title or operator name. Titles can be omitted as they will be taken from the first `Heading 1` element. -Here is a same `toc.yml` but this time with a nested table of content layout (articles will only be visible when group headings are clicked). +Here is the same `toc.yml` but this time with a nested table of content layout (articles will only be visible when group headings are clicked). ```yml - href: ../index.md @@ -53,13 +53,13 @@ Here is a same `toc.yml` but this time with a nested table of content layout (ar ### Manual section -For the `Manual` section we typically see these elements: +For the `Manual` section we typically include the following elements: -- Getting Started/Landing page - This typically includes a description of what the package does, how to install the package and funding/acknowledgements. This belongs in `docs/index.md`. -- Installation Instructions - If a package requires external dependencies or additional configuration it can be helpful to dedicate an extra page to this. -- Workflow/Conceptual Overview - Best illustrated with a flowchart or a basic workflow container. +- **Getting Started/Landing page** - This includes a description of what the package does, how to install the package, and any funding/acknowledgements. This belongs in `docs/index.md`. +- **Installation Instructions** - If a package requires external dependencies or additional configuration it can be helpful to dedicate an extra page to this. +- **Workflow/Conceptual Overview** - Best supported by an accompanying flowchart or example workflow. -Beyond that, there are many possible ways to organize the rest of the manual articles depending on the type of package that is being described. +Beyond that, there are many possible ways to organize the rest of the manual articles depending on the type of package that is being described. #### Individual operator articles @@ -70,9 +70,9 @@ One approach that we recommend is to try and write articles for each individual - Writing individual operator articles ensures complete coverage of all operators. Creating an individual operator article requires some additional steps. -For example, to create an individual operator article for a `Timer` operator to be included in a `Manual` article as well as in the automatically generated `Reference` docs: +For example, to create an individual article for a `Timer` operator to be included in both a `Manual` article as well as in the automatically generated `Reference` docs: -1) Create the `Bonsai_Reactive_Timer.md` article and place it in the `docs/apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the namespace.operator format. +1. Create the `Bonsai_Reactive_Timer.md` article and place it in the `docs/apidoc` folder. To utilize the `overwrite` function, in the markdown file, assign a UID that follows the `namespace.operator` format. ```yml --- @@ -80,8 +80,7 @@ uid: Bonsai.Reactive.Timer --- Write content here. ``` - -1) Create a new article markdown file and place it in the `docs/articles` folder. In this markdown file, include a reference to the individual operator.md file. +2. Create a new article markdown file and place it in the `docs/articles` folder. In this markdown file, include a reference to the individual operator `.md` file. ```markdown Some documentation content. @@ -93,12 +92,12 @@ Some documentation content. ### Reference section -As mentioned the `Reference` section of the website is auto-generated from [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) in the code. We have integrated into the Bonsai Editor the ability to right-click on individual operators and select `View Help`. This will bring up and load the `Reference` page for that operator in the editor itself. For most people, this might be the most obvious entry point to the package documentation. Thus it is essential that developers ensure that: +The `Reference` section of the website is auto-generated from [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) in the code. We have integrated into the Bonsai Editor the ability to right-click on individual operators and select `View Help`. This will bring up and load the `Reference` page for that operator in the editor itself. For most people, this might be the most obvious entry point to the package documentation. Thus it is essential that developers ensure that: -1) XML documentation comments are clear, simple and helpful. -2) Where appropriate, supplement additional information (basic workflow, images, long-form content) with an individual operator article using the `overwrite` function detailed in the previous section. +1. XML documentation comments are clear, simple and helpful. +2. Where appropriate, supplement the reference article with additional information (basic workflow, images, long-form content) by using the `overwrite` function detailed in the previous section. -At present, we understand that the default template for the `Reference` page is a little too technical, and somewhat confusing to navigate. We are in the midst of revamping the template to cater to a broader audience and will update this section when it becomes available. +At present, we understand that the default layout for the `Reference` page is a little too technical, and somewhat confusing to navigate. We are currently in the process of revamping the template to cater to a broader audience and will update this section when it becomes available. ### Tutorials section @@ -119,7 +118,7 @@ In addition, the `docfx.json` file needs to be modified to import the relevant r In `docfx`, articles are written in [Markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet) and rendered with the [Markdig](https://github.com/xoofx/markdig) parsing engine. Refer to these links for more information on how to format content in markdown. -When writing articles, please follow the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: +When writing articles, we highly recommend following the [MSDN writing tips](https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips). In particular: - Keep article and section titles short and succinct so that the table of contents that appears on the left and right sidebar are easier to read (and also to assist in machine translation). - Reuse operator names, properties, and descriptions in the articles and titles (do not use synonyms) so that readers may more easily follow and refer to them. @@ -144,7 +143,7 @@ For content in a different folder, use `../` to navigate up to the parent folder ### Cross-references and highlights -When working on an article, first check [the main documentation](../index.md) and confirm whether written material already exists that could be linked to avoid duplication. Also include links to resources like websites for external libraries which may be useful to explore for more information. +When working on an article, first check [the main Bonsai documentation](../index.md) and confirm whether written material already exists that could be linked to avoid duplication. Also include links to resources like websites for external libraries which may be useful to explore for more information. **Example:** @@ -176,7 +175,7 @@ Highlight folders, filenames, package names, functions, actions, editor/website When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in docfx](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). -For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To reference this you need to specify the full path to it including namespace, operator name, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. +For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To create a reference to this node you need to specify the fully qualified name of the operator, including its namespace, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the fully qualified name for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit `F12`. When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). @@ -196,7 +195,7 @@ You can also link to operators in other packages if their [xrefmap](./documentat ### Bonsai workflows To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName-workflowName.bonsai`. -Add the `.bonsai` file to the `workflows` folder in the repository. In the text of the article that includes/references this example workflow, add a workflow container. +Add the `.bonsai` file to the `workflows` folder in the repository. In the text of the article that includes/references this example workflow, add a workflow custom container. **Example:** @@ -208,7 +207,7 @@ Assuming you want to include `CustomPulseTrain-SendCustomWaveform.bonsai`: ::: ``` -Workflow images are automatically exported as SVG files by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule and requires the [build.ps1](./documentation-docfx.md#docfx-folder-organization) file and a [local bonsai environment](./documentation-docfx.md#repository-organization). +Workflow images are automatically exported as SVG files by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. The steps below require an existing [build.ps1](./documentation-docfx.md#docfx-folder-organization) file and a [local bonsai environment](./documentation-docfx.md#repository-organization). To generate the images locally for the `docfx` local preview, navigate to the `docs` folder and run this command (make sure `build.ps1` has been modified to point to the package src): @@ -216,19 +215,19 @@ To generate the images locally for the `docfx` local preview, navigate to the `d ./build.ps1 ``` -If any of the nodes are greyed out in the generated SVG, then additional packages need to be installed in the local bonsai environment by using the package manager in the local bootstrapper `Bonsai.exe`. +If any of the nodes are greyed out in the generated SVG, then additional packages need to be installed in the local bonsai environment by using the package manager. ### Figures > [!NOTE] -> Avoid images/screenshots when possible as they do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. +> Avoid images/screenshots as much as possible possible as they often do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. To include a figure or image in an article: -1) Save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`. -2) Add the figure/image to the `images` folder in the repo. -3) Reference the figure in the article with the following code. -4) (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute on the img element directly like follows. +1. Save your figure or image as a `.svg` or `.png` file, naming the file using the pattern `[article filename]-[figure name].svg`. +2. Add the figure/image to the `images` folder in the repo. +3. Reference the figure in the article with the following code. +4. (Optional) For smaller screenshots, it may help to set a max width so that the fonts do not blow up too much on desktop displays. This can be done by setting a `width` attribute directly on the `img` element as in the example below. **Example:** @@ -238,7 +237,7 @@ To include a figure or image in an article: ### Diagrams and Charts -Use [Mermaid](https://mermaid.js.org/) graphs to visualize flowcharts or pipelines. +Consider using [Mermaid](https://mermaid.js.org/) graphs to describe and visualize flowcharts or pipelines. **Example:** @@ -306,7 +305,7 @@ dotnet tool install --local docfx --version 2.75.3 ### Alerts -Use alerts to alert users to important information. Only use either the `Note` or `Warning` alerts as the color scheme does not conflict with the formatting for property names. +Use alerts to highlight the awareness of important information. Prefer the `Note` and `Warning` alerts as the color scheme does not conflict with the formatting for property names. **Example:** ```markdown @@ -325,4 +324,3 @@ Use alerts to alert users to important information. Only use either the `Note` o ### Final Polishing Steps Delete redundant blank rows in between lines and at the end of the articles. This improves code readability for future contributors. - From 9ecbd9a6f98a7cb8a366567b1af410639c41e072 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Tue, 3 Dec 2024 21:13:46 +0000 Subject: [PATCH 32/35] Link to a more complete workflow export example --- articles/documentation-docfx.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index 8e30bb46..f3d459a4 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -28,7 +28,7 @@ dotnet new install Bonsai.Templates dotnet new bonsaienv ``` -- `.github/workflows/` - The `docfx` website is often automatically published to [GitHub Pages](https://pages.github.com/) using a [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow specified in the `docs.yml` file. Unfortunately these workflows tend to be very project specific and we do not yet have a standardized pipeline. For a minimal example and inspiration you can check [the workflow for this repository](https://github.com/bonsai-rx/docs/blob/main/.github/workflows/build.yml). +- `.github/workflows/` - The `docfx` website is often automatically published to [GitHub Pages](https://pages.github.com/) using a [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) workflow specified in the `docs.yml` file. Unfortunately these workflows tend to be very project specific and we do not yet have a standardized pipeline. For a minimal example and inspiration you can check the workflow on a package repository that has been recently updated, e.g. [bonsai-rx/zeromq](https://github.com/bonsai-rx/zeromq/blob/main/.github/workflows/docs.yml). ## Setup docfx From 3a60f67952950eac913787163eaf3104f895cc79 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Tue, 3 Dec 2024 21:49:11 +0000 Subject: [PATCH 33/35] Move explanation of common workflow infrastructure --- articles/documentation-docfx.md | 26 +++++++++++++++++++------- articles/documentation-style-guide.md | 23 +---------------------- 2 files changed, 20 insertions(+), 29 deletions(-) diff --git a/articles/documentation-docfx.md b/articles/documentation-docfx.md index f3d459a4..845e2016 100644 --- a/articles/documentation-docfx.md +++ b/articles/documentation-docfx.md @@ -85,7 +85,7 @@ The documentation guides assume the `docs` folder is organized according to the ... ``` -- `bonsai/` - this folder is where we initialize the submodule referencing [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from `Bonsai` workflows (if you want to include them in your article) and adds a CSS template for `Bonsai` workflow containers (these containers allow users to easily copy workflows into the `Bonsai` editor). To create this submodule, run this command in the `docs` folder: +- `bonsai/` - this folder is where we initialize the submodule referencing [docfx-tools](https://github.com/bonsai-rx/docfx-tools). This submodule contains scripts for automating image export from `Bonsai` workflows (if you want to include them in your article) and also common infrastructure for [workflow containers](#creating-example-workflows). To create this submodule, run this command in the `docs` folder: ```powershell git submodule add https://github.com/bonsai-rx/docfx-tools bonsai @@ -285,13 +285,25 @@ To keep your online GitHub repository clean, you can use `.gitignore` files to i ## Creating example workflows -To write documentation for [new packages or releases](./create-package.md) that have not yet been published to the community, it is good practice to start by writing test workflows in Visual Studio. +To include an example workflow in an article of the documentation, first create the example workflow using the [local bonsai environment](#repository-organization) and save it as `articleFileName-workflowName.bonsai` into the `workflows` folder. In the text of the article that references this example workflow, add a workflow custom container. -1. Install [Visual Studio](https://www.visualstudio.com/) (the community edition can be installed for free for open-source projects). -2. Install Bonsai VS Extensions. Assuming Bonsai is already installed, from the Windows Start Menu, search for the "Install Bonsai VS Extensions" shortcut and run it. -3. In Visual Studio, open `src/PackageName.sln` in the repository. -4. Press F5 to open the Bonsai editor with the new package added. -5. From here, you can make Bonsai workflows and save them to the `workflows` folder as examples. +For example, assuming you want to include `CustomPulseTrain-SendCustomWaveform.bonsai`: + +```markdown +:::workflow +![Send Custom Waveform](../workflows/CustomPulseTrain-SendCustomWaveform.bonsai) +::: +``` + +Workflow images are automatically exported as SVG files by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. The steps below require an existing [build.ps1](#docfx-folder-organization) file and a [local bonsai environment](#repository-organization). + +To generate the images locally for the `docfx` preview, navigate to the `docs` folder and run this command (make sure `build.ps1` has been modified to point to the correct package folder in `src`): + +```powershell +./build.ps1 +``` + +If any of the nodes are greyed out in the generated SVG, then additional packages need to be installed in the local bonsai environment by using the package manager. ## Troubleshooting diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index b84d055f..8c18012f 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -194,28 +194,7 @@ You can also link to operators in other packages if their [xrefmap](./documentat ### Bonsai workflows -To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor and save the workflow as `articleFileName-workflowName.bonsai`. -Add the `.bonsai` file to the `workflows` folder in the repository. In the text of the article that includes/references this example workflow, add a workflow custom container. - -**Example:** - -Assuming you want to include `CustomPulseTrain-SendCustomWaveform.bonsai`: - -```markdown -:::workflow -![Send Custom Waveform](../workflows/CustomPulseTrain-SendCustomWaveform.bonsai) -::: -``` - -Workflow images are automatically exported as SVG files by the [docfx-tools](https://github.com/bonsai-rx/docfx-tools) submodule. The steps below require an existing [build.ps1](./documentation-docfx.md#docfx-folder-organization) file and a [local bonsai environment](./documentation-docfx.md#repository-organization). - -To generate the images locally for the `docfx` local preview, navigate to the `docs` folder and run this command (make sure `build.ps1` has been modified to point to the package src): - -```powershell -./build.ps1 -``` - -If any of the nodes are greyed out in the generated SVG, then additional packages need to be installed in the local bonsai environment by using the package manager. +To include example workflows in an article always consider using [custom workflow containers](./documentation-docfx.md#creating-example-workflows) as this makes it possible to copy workflows directly from the documentation into the editor. ### Figures From 28e32bfbeeb6cd93d0750348ca362e9704c4c2a2 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Tue, 3 Dec 2024 21:50:47 +0000 Subject: [PATCH 34/35] Rephrase to improve readability --- articles/documentation-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index 8c18012f..4eca1253 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -8,7 +8,7 @@ In general, we have converged on three types of articles, organized into distinc * `Manual` - articles explaining the core concepts of the package and functions of its various operators. * `Reference` - technical documentation for each operator, generated automatically by `docfx` from XML comments in source code or supplemented with individual operator articles. -* `Tutorials` - examples or tutorials about using the package. This section is optional, but valuable for more complex applications or when packages interoperate deeply with other packages. +* `Tutorials` - examples or tutorials about using the package. This section is optional, but valuable when examples require extensive integration with other packages. To construct these sections: From 2bcd6d23940f97224ad1f4752285db2a18789ff0 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Tue, 3 Dec 2024 21:52:50 +0000 Subject: [PATCH 35/35] Remove duplicate word --- articles/documentation-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/documentation-style-guide.md b/articles/documentation-style-guide.md index 4eca1253..5f49e0b1 100644 --- a/articles/documentation-style-guide.md +++ b/articles/documentation-style-guide.md @@ -199,7 +199,7 @@ To include example workflows in an article always consider using [custom workflo ### Figures > [!NOTE] -> Avoid images/screenshots as much as possible possible as they often do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. +> Avoid images/screenshots as much as possible as they often do not display well across light/dark mode and do not scale well across different display sizes and resolutions. See the following sections for alternative ways of creating different content. To include a figure or image in an article: