Major Website Update

[fsenf]

This is a follow-up of #470 - an imitative to update our website.

Let's try to document further development here, i.e.

• what needs top be done
• and who is working on and implementing updates
  as long this is in a draft stage.

Here #473 , we documented minimum requirements for a homepage release. I repeat it to have everything at one place:

• meaningful images without duplication
• content-rich landing pages for each entry point from page menu
• correct API section
• Hide API functions
• check passed that no content from earlier implementation is lost

[fsenf]

I discussed with @Sven-248 today that he might look into the "Section Navigation" thing.

[github-actions]

Linting results by Pylint:

Your code has been rated at 8.33/10 (previous run: 8.33/10, +0.00)
_{The linting score is an indicator that reflects how well your code version follows Pylint’s coding standards and quality metrics with respect to the RC_v1.6.x branch.
A decrease usually indicates your new code does not fully meet style guidelines or has potential errors.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.55%. Comparing base (f166b27) to head (f4b685a).
⚠️ Report is 153 commits behind head on RC_v1.6.x.

Additional details and impacted files

@@              Coverage Diff              @@
##           RC_v1.6.x     #477      +/-   ##
=============================================
- Coverage      63.56%   63.55%   -0.01%     
=============================================
  Files             27       27              
  Lines           3859     3858       -1     
=============================================
- Hits            2453     2452       -1     
  Misses          1406     1406              

Flag	Coverage Δ
unittests	63.55% <100.00%> (-0.01%)	⬇️

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.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[freemansw1]

Thanks, @fsenf . I've been working on debugging the API page and have it most of the way there. I'll push those changes when it's working.

[freemansw1]

I've updated the API pages to work properly now. I've removed some of the documentation pages, especially from anything internal.

One question I have for the group is whether or not to start hiding functions from the API documentation. Take tobac.feature_detection.feature_position as an example. It should only be called internally, I cannot think of a reason for it to be called externally. We can remove it (or any other function) from the docs by adding :meta private: to the docstring. I think that would be a good idea for us to do.

[fsenf]

@freemansw1 : Great update! API reference looks nice now!

I agree to hide everything that is not primarily used externally. This keeps the API docs clear.

[fsenf]

I added our example thumbnails to the entry point of our homepage. There is room for improvement ... What does the group think?

see: https://tobac--477.org.readthedocs.build/en/477/

[freemansw1]

I added our example thumbnails to the entry point of our homepage. There is room for improvement ... What does the group think?

see: https://tobac--477.org.readthedocs.build/en/477/

Thanks, @fsenf . That is a significant improvement. I think, broadly, we should find a way to have the homepage take up more of the page, and have less whitespace. Perhaps that means switching homepage templates, perhaps that just means expanding the content some. Right now, I'm working on figuring out hiding private API functions (:meta private: did not work by itself).

[freemansw1]

Per our discussion last meeting, I've moved this to post-v1.6. Per our usual policy on documentation, we can release this without a version increment, but I think an email announcement would be nice.

[JuliaKukulies]

Such great work @freemansw1 ! It looks very good and I would be happy to get this new website published now.

A few minor things (maybe only the API-related comments need to be solved before merging, rest can wait):

• The API link "See API reference" on the index page does currently not work

• When you access the API references through the "API" tab in the top menu, it works, but the methods for the tobac.feature_detection module is incomplete. Not sure why this is only the case for the feature detection and not for the other modules

• Maybe we could add the dask logo as a thumbnail for "Parallel Processing" in the Example Gallery

• Is the "How to check the Sphinx-based rendering" in the Developer guide still accurate for the new webpage?

• I think the hierarchy of the developer guide sections might be a bit confusing right now since the "Contributing" page does not appear int he Section navigation, but does contain a lot of subsections. Would it be much work to have it similar to the "User guide" page, where the first page just contains an overview of all subsections?

• Update subsection "Code reviews" to be consistent with our new one reviewer policy ( Thanks for integrating my changes later in the branching strategy section of the developer guide, but just realized we had another section on code reviews that needs to be updated, too)

[JuliaKukulies]

Before anything is merged into the release branch (:code:RC_*), we require that one reviewer accepts the code changes of a pull request.

[fsenf]

Based on @JuliaKukulies 's comment, I checked and updated the sphinx-based rendering docu. All is correct now.

[freemansw1]

Thanks, @JuliaKukulies . I've made the revisions you requested. Thanks for the detailed look through!

• When you access the API references through the "API" tab in the top menu, it works, but the methods for the tobac.feature_detection module is incomplete. Not sure why this is only the case for the feature detection and not for the other modules

I'm not sure what you mean here. If it is what I think it is, I diliberately hid most of the functions in feature detection, as they really shouldn't be used by end-users. Let me know if you want more of the functions visible.

[JuliaKukulies]

Thanks, @JuliaKukulies . I've made the revisions you requested. Thanks for the detailed look through!

• When you access the API references through the "API" tab in the top menu, it works, but the methods for the tobac.feature_detection module is incomplete. Not sure why this is only the case for the feature detection and not for the other modules

I'm not sure what you mean here. If it is what I think it is, I diliberately hid most of the functions in feature detection, as they really shouldn't be used by end-users. Let me know if you want more of the functions visible.

Oh OK, I think that this makes sense then. Yes, my comment was that the only function visible in the module is tobac.feature_detection.feature_detection_multithreshold() but I believe that is also the only one we want end users to utilize, so I am fine with that reasoning.

Thanks for implementing all the changes qo quickly. It looks really good now and I am happy for this to being merged!

[freemansw1]

Thanks to @grleung for taking a look at the new docs and providing some comments. I've incorporated her very good suggeestions now.

[freemansw1]

Given that @JuliaKukulies has formally approved this and everyone had a chance to provide comments at the last dev meeting, I'm going to merge this. We'll release as part of v1.6.2. Thanks, all.