Docs/overhaul

[MischaPanch]

Closes #916

This PR presents an overhaul of how the docs are built and presented

1. Notebooks are no longer just links in some drive. They are checked in without their outputs, executed in CI, and thereby serve as integration tests as well as tutorials. They have been adjusted to work with the current master branch
2. Execution of notebooks is cached, so it's very fast
3. The api docs are generated automatically with a custom script. Previously this was only done for the highlevel module
4. The build is happening with jupyter-book (which still uses sphinx in the backend). It is using the default jupyter book theme, which I think looks very nice and adds useful navigation to the right side of the screen
5. Customized api docs rendering for better appearance
6. The toc of the docs is built automatically with jupyter-book. The api docs generation script has been adjusted accordingly
7. The viewcode and linkcode extensions add source code and links to it to the docs
8. A bunch of docstrings have been adjusted to better reflect the configured rules
9. Several typing issues improved to make mypy happy

It was quite a piece of work, I hope you like the result :)

[MischaPanch]

I now see that there are some typing issues, maybe some ignored rules were accidentally deleted from pyproject. Will look into it asap

[MischaPanch]

@opcode81 Have a look, if you want to. If you like this style, we could use a similar setup for sensai

[codecov-commenter]

Codecov Report

Attention: 7 lines in your changes are missing coverage. Please review.

Comparison is base (8d3d1f1) 88.09% compared to head (5f4a02c) 88.06%.

❗ Current head 5f4a02c differs from pull request most recent head 4c24dc6. Consider uploading reports for the commit 4c24dc6 to get more accurate results

Files	Patch %	Lines
tianshou/utils/logging.py	72.72%	6 Missing ⚠️
tianshou/utils/string.py	96.55%	1 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #999      +/-   ##
==========================================
- Coverage   88.09%   88.06%   -0.04%     
==========================================
  Files          96       96              
  Lines        7527     7531       +4     
==========================================
+ Hits         6631     6632       +1     
- Misses        896      899       +3     

Flag	Coverage Δ
unittests	88.06% <89.06%> (-0.04%)	⬇️

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.

[Trinkle23897]

Is there an online link for preview? Also I can give you current rtd permission if you want

[MischaPanch]

Is there an online link for preview? Also I can give you current rtd permission if you want

Working on having it run in rtd - it's a painful journey. Almost done, I think, then I'll post the link for preview.

My rtd profile name is MischaPanch, associtated to my GH account. Could you give me access to tianshou's official rtd project?

[MischaPanch]

Finally, the rtd build worked! Here

https://tianshou-fork.readthedocs.io/en/latest/

[MischaPanch]

I now see that the notebook outputs were not added, gonna fix that tomorrow

[Trinkle23897]

love it, just added you to official rtd maintainer. there's an email need to click for accepting invitation

[nuance1979]

Finally, the rtd build worked! Here

https://tianshou-fork.readthedocs.io/en/latest/

Looks great! However, the API docs do not show up. Is that expected?

[MischaPanch]

@Trinkle23897

Completely done now, see https://tianshou-fork.readthedocs.io/en/latest/

Notebooks are executed and the api docs are also working fine. Had to dive deeper into rtd-docker-poetry stuff than I ever wanted to.

@opcode81 helped in improving the task running, making them platform independent

I force pushed and cleaned the history. I'd merge this without squashing after the checkmark, if that's ok.

[MischaPanch]

Finally, the rtd build worked! Here
https://tianshou-fork.readthedocs.io/en/latest/

Looks great! However, the API docs do not show up. Is that expected?

They do now

[MischaPanch]

Note that the main page for the api docs is empty, since the toc is displayed to the left and I didn't want to duplicate the pages for modules as well as init files. But if you go to the page of one of the modules, you get

https://tianshou-fork.readthedocs.io/en/latest/03_api/data/batch.html

Note the link to the source code, which is also uploaded to the docs and rendered there

[MischaPanch]

I improved the API docs landing page now, will be built in about 20 mins. Added a subtitle and displayed links to direct children, like for all subpackages

[nuance1979]

LGTM. Great work!