Update docs README with new contribution workflow #82
Conversation
glopesdev
changed the title
README.md
Outdated
| - .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. |
There was a problem hiding this comment.
We might want to consider mentioning here how to build the solution in order to export the example workflows, and in that case also consider how to automate the msbuild part into the powershell module containing the export image functions.
README.md
Outdated
| - .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. |
There was a problem hiding this comment.
We should maybe include these as part of docfx-tools or some other template repo.
README.md
Outdated
| href: articles/ | ||
| - name: Reference | ||
| href: api/ | ||
| - name: Tutorials |
There was a problem hiding this comment.
We might want to consider marking the Tutorials section as optional for other package documentation, to make things simpler as a common reference.
README.md
Outdated
| 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)] |
There was a problem hiding this comment.
Review format of relative / local URLs to make sure we have a solution that works for both local and remote builds.
README.md
Outdated
| 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. |
There was a problem hiding this comment.
It might be worth mentioning as a note the importance of matching the publishing URL with the PackageProjectUrl attribute specified in the .csproj files. This is where the Bonsai editor will look for the xrefmap.yml file to retrieve URLs for operators.
|
@banchan86 I was going over the guide again, and was wondering whether this should be part of the docs README, or instead actually be an article inside the main bonsai docs, perhaps part of a larger guide on how to create new packages. Then in the README.md of this repo we could still point to this other article in case people drop by looking for guidance on how to create docs. Let's discuss better at the next meeting. |
|
Oops accidentally closed this because I was rearranging my repo workspace, but I plan to reopen this with the changes addressed |
This PR updates the instructions in README.md to reflect the most recent changes to the workflow for setting up and editing Bonsai docs.
An online version of this PR is available at https://github.com/banchan86/bonsai_docs_test/