Solving the bug in API docs rendering

[fsenf]

• Have you followed our guidelines in CONTRIBUTING.md?
• Have you self-reviewed your code and corrected any misspellings?
• Have you written documentation that is easy to understand?
• 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?
• Have all tests passed in your local clone?
• If you have introduced a new functionality, have you added an example notebook?
• Have you kept your pull request small and limited so that it is easy to review?
• Have the newest changes from this branch been merged?

This solve the RTD rendering bug:

• included numpy in installation requirement and exclude numpy from mock list
• made a short documentation how to run sphinx-based rendering locally
• this solves RC_v1.5.0 API docs broken #297

[JuliaKukulies]

Thanks for the help with this @fsenf ! This works well and fixes the API. I am fine with this change, but want to double check with @freemansw1 and @w-k-jones if this is the preferred fix, as I am not sure if there are any significant adverse implications of making numpy a dependency instead of mocking it.

Also, we might want to add tobac.utils.internal and tobac.utils.periodic_boundaryto doc/tobac.rst and I am wondering if we should move Testing-Sphinx-based-Rendering.md to the developer guide.

[JuliaKukulies]

Would it be useful to add instructions for how to test this on a certain pull request as well?

git fetch upstream pull/ID/head:BRANCH_NAME
git checkout BRANCH_NAME

[JuliaKukulies]

Super nice and helpful that you added an explanation here for how the sphinx rendering works! I am, however, wondering, if the developer guide is maybe the better location? :) It does also make sense to keep it in the doc/ folder, but I am generally in favor of having one common place instead of many different readme markdown files.

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (90ba004) 54.60% compared to head (40b104a) 54.60%.

❗ Current head 40b104a differs from pull request most recent head 054588d. Consider uploading reports for the commit 054588d to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           RC_v1.5.0     #305   +/-   ##
==========================================
  Coverage      54.60%   54.60%           
==========================================
  Files             15       15           
  Lines           3170     3170           
==========================================
  Hits            1731     1731           
  Misses          1439     1439           

Flag	Coverage Δ
unittests	54.60% <ø> (ø)

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

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[freemansw1]

Thanks so much for taking care of this, @fsenf. I'm happy with the PR, but have the same thought as @JuliaKukulies on moving the testing into the developer guide.

As long as RTD is happy with installing numpy instead of mocking it, I'm happy to do that.

[fsenf]

OK, good suggestion! I will update the PR and remove the markdown-based description in this PR.

To have a homogeneous format, I will convert the .md file to .rst and directly add it to PR #281.

[freemansw1]

Thanks, @fsenf. I'm happy with this now!

[JuliaKukulies]

Me too :) ready to merge!

[fsenf]

Nice, now I feel confident to push the green button.