Developing the developer guide

[JuliaKukulies]

This is a draft pull request to collaboratively work on the developer guide.

I have started to suggest some subsections and points to include based on the discussion in #265

Here we can look at how our progress looks like on read the docs: https://tobac--281.org.readthedocs.build/en/281/

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 60.71%. Comparing base (2fe56c0) to head (cf3c6bd).
Report is 46 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #281      +/-   ##
==========================================
+ Coverage   60.44%   60.71%   +0.26%     
==========================================
  Files          23       23              
  Lines        3522     3541      +19     
==========================================
+ Hits         2129     2150      +21     
+ Misses       1393     1391       -2     

Flag	Coverage Δ
unittests	60.71% <100.00%> (+0.26%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[fsenf]

@JuliaKukulies : I now added the sphinx-based rendering docu to this PR. I used pandoc to convert markdown to rst, but I am not sure with all code parts have been converted in the correct way. Could you have a look?

[JuliaKukulies]

Perfect @fsenf ! I added your file to index.rst but for some reason the page does not show up. At a first glance the conversion looks good, but I will check in more detail.

[fsenf]

I made some updates to the dev guide which will come with the next direct commit to the branch.

All looks good beside that these topics still need to be described in detail in doc/contributing.rst

• Github actions / workflow
• unit testing -> How to add a unit test
• jupyter notebook examples

It would be great to get support from @freemansw1 and @w-k-jones for describing the first two items. I could care for the last item.

Should make separate rst file for each topic to make the content easier to diggest?

[JuliaKukulies]

Great, thanks for your updates @fsenf ! I think it is a good idea to have separate .rst files for these items as they are a bit more comprehensive. The structure of the dev guide is also just a first draft suggestion, so feel free to change it where necessary!

What should we do with the CONTRIBUTING.md? Do you want to keep it or should we just make sure that all the information is somewhere in the dev guide? I personally find it better to have all on one place and remove CONTRIBUTING.md

[fsenf]

My suggestion would be:

• Keep CONTRIBUTING.md
• but reduce content to nice welcome words and a link list to the actual content in the dev guide

[JuliaKukulies]

My suggestion would be:

• Keep CONTRIBUTING.md
• but reduce content to nice welcome words and a link list to the actual content in the dev guide

I like this suggestion- let's do that!

[fsenf]

This dev doc is in a very good shape! Thank you a lot for your efforts! I just have a few minor comments and incorporated some spelling and formatting corrections.

[JuliaKukulies]

Thanks for your comments, @fsenf ! I think I addressed them all :)

[fsenf]

Once again, great work!

[fsenf]

@freemansw1 : Hi Sean, this PR is ready for a 2nd review. Do you think you can make it until the next dev meeting? Thanks, Fabian.

[fsenf]

Who agreed to be the 2nd reviewer here? Was it you @freemansw1 ?

[freemansw1]

Thanks, @JuliaKukulies and @fsenf .

We have one minor merge conflict to fix, but I would also be happy for this to be merged directly into main as it only touches documentation, per our policies around that kind of thing.

[JuliaKukulies]

Not super sure why the zenodo json check fails, since the formatting and syntax seemed to be OK after i updated my affiliation?

[JuliaKukulies]

All right, I fixed the json formatting issue, so I am merging directly into main as we have discussed before. Thanks @fsenf and @freemansw1 and lets make sure to continue to work and update the developer guide in the future.

[freemansw1]

All right, I fixed the json formatting issue, so I am merging directly into main as we have discussed before. Thanks @fsenf and @freemansw1 and lets make sure to continue to work and update the developer guide in the future.

See the JSON formatting CI was making sure that you complied with all new marketing requirements :) (I still don't know what the issue was, but glad it resolved).

[JuliaKukulies]

All right, I fixed the json formatting issue, so I am merging directly into main as we have discussed before. Thanks @fsenf and @freemansw1 and lets make sure to continue to work and update the developer guide in the future.

See the JSON formatting CI was making sure that you complied with all new marketing requirements :) (I still don't know what the issue was, but glad it resolved).

Haha goood :)

Also not sure what the issue was, I just copied the json file from another branch and it worked