Catalyst.jl icon indicating copy to clipboard operation
Catalyst.jl copied to clipboard

add some basic developer docs

Open isaacsas opened this issue 1 year ago • 3 comments

To help new contributors, these should

  1. Summarize where the various Catalyst components are located in the src/*.jl files.
  2. Summarize what PRs should include, i.e.
    • tests
    • updating HISTORY.md
    • adding to tutorials, and if exporting functions adding to the API
    • adding doc strings and the conventions used

isaacsas avatar Sep 18 '23 13:09 isaacsas

Related to this, would it make sense to split up the src folder into subfloders (like we have started with spatial)? It might also help with this since it makes it easier to see directly what is where (and where new stuff should go). Right now it is fine, but if we continue adding stuff we probably should do something like this sooner or later (or we get too many files in that folder).

  • "graphs.jl" and "latexify_recipes.jl" could be bundled (visualization?)
  • "reaction_network.jl", "reactionsystem.jl", "registered_functions.jl", and "expression_utils.jl" could maybe bundled? Although could be moved to a util folder, or maybe removed (since it only contains two really short functions right now).
  • "chemistry_functionality.jl", "networkapi.jl" could be grouped as "Other functionalities" or something. Basically stuff not part of the core workflow. If we get more chemistry related stuff though, we might be able to create a chemistry folder.

TorkelE avatar Sep 19 '23 03:09 TorkelE

I personally find the splitting of test files confusing, and can't ever find files now. It doesn't feel like we have so many src/*.jl files that this is needed yet (there are only 9...).

isaacsas avatar Sep 19 '23 15:09 isaacsas

This is on my list, but furthest away (after the current wave of PRs, the additional DSL options like equations and observables, MTK v9, and some additional docs design). I still think in tandem with this I would like to see some form of src housekeeping though:

  • The "reaction_network.jl" file should have a name including DSL I think.
  • Some function (e.g. esc_dollars!(ex)) should be moved to "expression_utils.jl".
  • I'm thinking (but not sure) whether make sense to split the "reactionsystem.jl" file into one solely defining the ReactionSystem structure, and another defining various coverts and stuff on it.
  • I still would like to try whether it would make sense to rename e.g. the docs folder into stuff like "01_introduction_to_catalyst" so that they appear in the same order in the file system as they do in the docs (currently finding the right file is always surprisingly annoying).

TorkelE avatar Nov 11 '23 01:11 TorkelE