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

Add script to automatically configure docfx.json #10

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

Add script to automatically configure docfx.json #10

banchan86 opened this issue Sep 17, 2024 · 0 comments · May be fixed by #11

Comments

@banchan86
Copy link

banchan86 commented Sep 17, 2024

Motivation
A pain point in setting up a new docfx website for Bonsai packages is that the docfx.json needs to be configured manually. This is currently done by checking other repositories to see which options to change or are no longer necessary, and then copying them over to the new docfx.json or copying the file itself.

  • Unnecessarily manual and tedious.
  • Runs the risk that some options are added unnecessarily and configured wrongly, and these errors might propagate forward, especially with new docfx updates.
  • Makes the guide to setting up a new docfx website a bit wordy/long.

Proposed solution
A script to automatically configure docfx.json would confer these advantages:

  • Streamline the process and make it more efficient.
  • Single point of maintenance that we could monitor and keep updated and that could be used as a reference.
  • Simplify the guide for setting up new Bonsai package docfx websites.

Additional context
I have gone back and forth on these two issues to consider with the script:

  • Whether the script should prompt if users want to add any of the options.
    • My preference right now is to keep it simple and not have any prompting since most of the options are necessary and users can still change and modify docfx.json after.
  • The level of checks to include in the file.
    • This would depend on how we expect users to use the script and whether it should guard against modifying an already modified file. My preference again is to keep it simple, and for users to use the script on a freshly created docfx.json, and then add their level of customisation on top, rather than for users to apply it on top of an already modified or old docfx.json. I think this is the right way to update an old docfx installation (since it refreshes the default docfx config) and avoids keeping old options around. Thus currently the script only has checks in place to make sure that if users for some reason run the script twice on a new docfx.json it does not mess up docfx.json.
@banchan86 banchan86 linked a pull request Sep 17, 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