Documentation page improvements

[freemansw1]

This PR brings over most of the documentation page improvements from #127 , and should pair nicely with #138 .

• [x] Have you followed our guidelines in CONTRIBUTING.md?
• [x] Have you self-reviewed your code and corrected any misspellings?
• [x] Have you written documentation that is easy to understand?
• [x] Have you written descriptive commit messages?
• [ ] Have you added NumPy docstrings for newly added functions?
• [ ] Have you formatted your code using black?
• [ ] If you have introduced a new functionality, have you added adequate unit tests?
• [x] Have all tests passed in your local clone?
• [ ] If you have introduced a new functionality, have you added an example notebook?
• [x] Have you kept your pull request small and limited so that it is easy to review?
• [x] Have the newest changes from this branch been merged?

To get his feet wet on reviewing, I've requested @pjmarinescu as a reviewer here. As one of the original tobac devs, I think his perspective on this will be really useful.

[freemansw1]

Ah- I've now added readthedocs building to PRs, which has just failed! It builds locally, but clearly, there is an issue with readthedocs. I'll work on revising the PR shortly.

[codecov[bot]]

Codecov Report

Merging #150 (4074eae) into RC_v1.4.0 (90fb3ff) will increase coverage by 3.24%. The diff coverage is n/a.

@@              Coverage Diff              @@
##           RC_v1.4.0     #150      +/-   ##
=============================================
+ Coverage      31.69%   34.93%   +3.24%     
=============================================
  Files             11       11              
  Lines           2051     2098      +47     
=============================================
+ Hits             650      733      +83     
+ Misses          1401     1365      -36     

Flag	Coverage Δ
unittests	34.93% <ø> (+3.24%)	:arrow_up:

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

Impacted Files	Coverage Δ
tobac/analysis.py	7.91% <0.00%> (ø)
tobac/segmentation.py	75.24% <0.00%> (ø)
tobac/centerofgravity.py	6.25% <0.00%> (ø)
tobac/plotting.py	3.08% <0.00%> (+<0.01%)	:arrow_up:
tobac/feature_detection.py	70.71% <0.00%> (+2.64%)	:arrow_up:
tobac/utils.py	46.75% <0.00%> (+5.71%)	:arrow_up:
tobac/tracking.py	64.48% <0.00%> (+8.93%)	:arrow_up:
tobac/testing.py	94.55% <0.00%> (+10.38%)	:arrow_up:

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[freemansw1]

Thanks to readthedocs, you can preview these new documents here: https://tobac--150.org.readthedocs.build/en/150/ (or by hitting details on the readthedocs action).

Also, given the relation to #138 , I've requested @snilsn as a third reviewer, if he is interested and has time.

[freemansw1]

I've gone through and made some substantial changes to this PR, including a new page describing some of the feature detection parameters and three new Jupyter notebooks addressing the same. I do plan to expand on this and do similar work on both the segmentation section and tracking section.

[freemansw1]

I wonder if we should move/copy the examples from the examples folder over to the readthedocs? Maybe that's a separate issue...

[snilsn]

I really like the new notebooks. Together with an updated documentation this should really make getting started with tobac easier.

We just have to keep in mind, that @fsenf and I have been working on a very similar thing in tobac-tutorials, based on v2. I'm planning to make a PR with notebooks on tracking and segmentation there soon.

I think more examples can never hurt, but we should probably discuss how to proceed to avoid redundancy.

[freemansw1]

Yes, agreed that I want to avoid duplication. I hadn't seen your new basics folder, and some of this definitely overlaps, although my code is written for v1.x rather than v2.x. As we progress into v2.x (and/or #143 is resolved), I think we should bring the basics notebooks over to the readthedocs to replace these notebooks? What are your thoughts?

Regardless, I think that we should discuss this at our developers' meeting this week.

[freemansw1]

Note that I've updated the documentation with the segmentation discussion here. I'm going to wait to request re-reviews until I add in the tracking discussion.

[JuliaKukulies]

Committed the publication page now to this PR. Let me know if you have any comments or requests for changes here!

[JuliaKukulies]

And sorry, I reverted my first two commits because I still had the old index.rst in my branch. Now everything should be clean and the last three commits contain the additions for the publication page. Feel also free to move it somewhere else if you think it is not the best location to have it after the examples.

[freemansw1]

I believe that I've addressed all the comments here.

I haven't yet finished (or even really started) the documentation on segmentation or tracking. I do want to do that, but I'm inclined to do that as a separate PR off of this one, once this one is merged? That will keep the review process simple. Let me know what you think @snilsn @JuliaKukulies @pjmarinescu

[JuliaKukulies]

Looks good @freemansw1, I am happy with the changes! And I agree that you it would be easier to include the documentation on segmentation and tracking in a separate PR as this one is already quite big.

[snilsn]

Good work @freemansw1 , I'm happy with these edits and also with splitting the work on the documentation into two PRs.

[freemansw1]

Thanks @snilsn and @JuliaKukulies . Given that @pjmarinescu has comments, I'll wait to hear from him before merging.

[pjmarinescu]

Agree regarding splitting into to PRs.

[freemansw1]

Thanks everyone!