Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create articles on docfx and documentation style guide #102

Open
banchan86 opened this issue Sep 19, 2024 · 0 comments · May be fixed by #103
Open

Create articles on docfx and documentation style guide #102

banchan86 opened this issue Sep 19, 2024 · 0 comments · May be fixed by #103

Comments

@banchan86
Copy link

Motivation

The current README which hosts instructions on how to create documentation with docfx is out of date and a little short on detail. It would also be good to standardize best practices for documentation, which currently is spread mainly through discussions with package developers/documentation writers. A previous attempt was made at #82, and as part of the feedback for that PR, it was brought up that it might be better to package this as an article. This would also serve as a good base for discussion during the documentation session for the upcoming Bonsai Developer Conference.

Proposed solution

While I was working on it, I found that it was getting too long and thought there was enough content to split it into two articles. Thus I propose making the following changes:

  • Documentation with docfx- This would cover repository and docs folder organization, installing docfx and docfx configuration, publishing to github pages, and troubleshooting tips

  • Documentation style guide - This would cover article organization, constructing the table of contents, using individual operator articles and the overwrite function, bonsai workflow image export and containers, standard formatting for operators and other common Bonsai content.

  • README.md - Trim it to just the basics for people to get started with contribution, with links to the articles on docfx and documentation style guide.

Additional issues to consider

  • Article Location - currently the articles does not fit nicely into the existing article categories, but Extending Bonsai is the closest since there is also a Create a Package article. I think creating a new section for Custom Package Development or even a Bonsai Developers subsection of the website would be a better fit (as it is not technically a manual article for normal Bonsai Users). There might not be enough content to go with the later option, but I think the package development articles also need to be expanded (unfortunately I have zero experience with that)
@banchan86 banchan86 linked a pull request Sep 19, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant