Docs #67

zmoon · 2021-10-27T20:46:10Z

I put together an initial docs build, addressing #60 and #13.

new Conda env xmovie-docs for docs build placed in ci/
- some of the things can be removed since the nbs don't need to be run
using sphinx-book-theme like xarray
some API references for the public stuff, adding to the docstrings
example gifs/pics currently used in the readme now all generated by the main example nb
- probably a lot of the readme examples could be removed since they are duplicated in the quickstart nb

To build the docs locally to check it out:

conda env create -f ci/environment-docs.yml
conda activate xmovie-docs
cd docs
sphinx-autobuild . _build/html

Remaining:

RTD configuration and link to docs in readme (maybe as the GH page website as well)
remove most stuff from readme that is duplicated by the quickstart nb
~~more docstrings?~~

review-notebook-app · 2021-10-27T20:46:14Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

codecov · 2021-10-27T20:53:17Z

Codecov Report

Merging #67 (b35750e) into master (63dd673) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #67   +/-   ##
=======================================
  Coverage   79.62%   79.62%           
=======================================
  Files           3        3           
  Lines         324      324           
  Branches       59       59           
=======================================
  Hits          258      258           
  Misses         43       43           
  Partials       23       23

Flag	Coverage Δ
unittests	`79.32% <ø> (ø)`

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

Impacted Files	Coverage Δ
xmovie/core.py	`87.04% <ø> (ø)`
xmovie/presets.py	`69.76% <ø> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 63dd673...b35750e. Read the comment docs.

jbusecke · 2021-12-07T16:43:18Z

Hey @zmoon, first of all sorry for the late reply. I was just completely swamped with other projects. Is this PR ready for review or can I help with anything?

zmoon · 2021-12-07T23:28:56Z

Hi @jbusecke yeah I think it is ready for your initial review. I didn't do this yet:

probably a lot of the readme examples could be removed since they are duplicated in the quickstart nb

I think I was waiting to see what you thought

Also have to configure ReadTheDocs and add link to readme, etc., but can do that after you review the initial docs.

zmoon · 2021-12-08T01:27:23Z

Also, for the rotating globe examples, I think a dataset that covers the whole globe would be more exciting, maybe you have something in mind that would be easy to use?

jbusecke · 2021-12-08T14:33:12Z

I think it would be nice to get started with a smaller example and then build on it with further PRs?

I just activated RTD builds for PRs, but I am not sure if it will run if I just restart the GH actions (which I just did).

jbusecke · 2021-12-08T14:34:00Z

It seems like it is not triggering. So I guess that is even more reason to merge this now and see how it looks haha.

jbusecke

Thanks a ton @zmoon for all these changes. I really appreciate all the work you put into this (I only just now realized how much is fixed here 🤪).

I made a few suggestions. Once those are implemented I will build it locally and then merge?

jbusecke · 2021-12-08T14:35:50Z

ci/environment-docs.yml

+  #
+  - pip
+  - pip:
+    - '-e ../'  # xmovie


I am not sure about this part here. I would prefer to add a short contributor guide, with instructions on how to set up the env and then install xmovie with pip install -e ., because this here might mess with RTD?

The issue is that xmovie needs to be installed ~~or at least importable~~ (for setuptools_scm to have worked) since I am loading the version from it. This is a pretty foolproof method. I can confirm it is valid Conda env spec and doesn't mess with RTD.
Xarray does the same thing.
I do think contributor guide with instructions for setting up the envs for normal work and docs work would be a good addition!

docs/conf.py

docs/whats-new.rst

xmovie/core.py

zmoon · 2021-12-08T16:35:08Z

It seems like it is not triggering. So I guess that is even more reason to merge this now and see how it looks haha.

Yeah, I don't think it will until the config file is in the default branch. And then if you want to build for PRs you have to enable in your settings (Edit: now I see that you said earlier that you already did this).

zmoon · 2021-12-08T16:46:05Z

I think it would be nice to get started with a smaller example and then build on it with further PRs?

Ok yeah, future PR for changing or adding example makes sense, just wanted to mention it.

jbusecke · 2021-12-08T20:06:17Z

Yeah, I don't think it will until the config file is in the default branch. And then if you want to build for PRs you have to enable in your settings.

Definitely did that, but I think I have encountered this before. Ill merge this once the changes are implemented.

- more detailed install instructions - trim install instructions in readme

zmoon · 2021-12-10T04:11:11Z

@jbusecke I think it is ready for you to check out the build locally and let me know what you think

jbusecke · 2021-12-15T02:08:13Z

Just built it locally and it looks great! Ill merge this now and we can see how it looks on RTD

zmoon · 2021-12-15T03:09:13Z

Looks like it got Command killed due to excessive memory consumption during the conda create. Are you able to request a rebuild?

jbusecke · 2021-12-16T14:51:40Z

Oh darn. I retriggered the build, but I am pretty sure it will fail again. Are we executing the notebooks on RTD? We might want to switch back to just pushing rendered notebooks...xmovie might be a bit resource hungry for the RTD resources?

jbusecke · 2021-12-16T14:54:17Z

I also have the option to do this:

But I am not quite sure about the implications. Do you have any experience with this @zmoon ?

zmoon · 2021-12-16T15:29:46Z

Oh darn. I retriggered the build, but I am pretty sure it will fail again. Are we executing the notebooks on RTD? We might want to switch back to just pushing rendered notebooks...xmovie might be a bit resource hungry for the RTD resources?

By default nbsphinx won't execute the nbs unless they are output-free. So we don't have to worry about that (they are stored in the repo with the outputs). That first failure was during the Conda env creation; it didn't even get to the docs build. And I see this time it has been stuck there for a while too. Given that we are not executing the nbs, maybe after #71 I can create a minimal requirements.txt for RTD to use to make this part faster.

I haven't tried the "Remove build environment for latest", but it doesn't sound like it would hurt anything, might as well try it.

jbusecke · 2021-12-16T16:57:37Z

I think reducing the dependencies is a good thing, no matter what. We could also try to use mamba to solve this issue. I believe I have done that in another project of mine (Ill dig through some repos later).

zmoon · 2021-12-16T18:22:07Z

Also, I didn't properly link them, but I believe you could close #13 and #60 now

zmoon added 13 commits October 26, 2021 21:17

wip

64721e7

filter some annoying shapely warnings from cartopy

5febc78

Add headings, fix custom plotfunc example

14e0ef7

Initial docs Conda env

3800c4a

Initial docs with some api ref and whats-new

7acc976

intersphinx; docstring work

922abe8

Example notebooks in docs; restore movie length

8dd1c2b

Generate all example images in first-steps

fe96425

Rename example nbs

78f9dbe

Reorder index

e54481f

Replace readme image refs

67a07dc

Remove unused files in docs/

5514df9

More quickstart nb cleanup

9807887

Merge branch 'master' into docs

37c5558

zmoon marked this pull request as ready for review December 7, 2021 23:29

jbusecke requested changes Dec 8, 2021

View reviewed changes

zmoon added 4 commits December 9, 2021 20:02

Address some review comments

4bbf7e7

add rtd config file

9a698fe

readme edits

9145d71

Main docs page work

b35750e

- more detailed install instructions - trim install instructions in readme

zmoon mentioned this pull request Dec 10, 2021

Lighten requirements? #71

Open

jbusecke merged commit 023abcb into jbusecke:master Dec 15, 2021

zmoon deleted the docs branch May 3, 2022 22:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs #67

Docs #67

zmoon commented Oct 27, 2021 •

edited

Loading

review-notebook-app bot commented Oct 27, 2021

codecov bot commented Oct 27, 2021 •

edited

Loading

jbusecke commented Dec 7, 2021

zmoon commented Dec 7, 2021 •

edited

Loading

zmoon commented Dec 8, 2021

jbusecke commented Dec 8, 2021

jbusecke commented Dec 8, 2021

jbusecke left a comment

jbusecke Dec 8, 2021

zmoon Dec 8, 2021 •

edited

Loading

zmoon commented Dec 8, 2021 •

edited

Loading

zmoon commented Dec 8, 2021

jbusecke commented Dec 8, 2021

zmoon commented Dec 10, 2021

jbusecke commented Dec 15, 2021

zmoon commented Dec 15, 2021

jbusecke commented Dec 16, 2021

jbusecke commented Dec 16, 2021

zmoon commented Dec 16, 2021 •

edited

Loading

jbusecke commented Dec 16, 2021

zmoon commented Dec 16, 2021

Docs #67

Docs #67

Conversation

zmoon commented Oct 27, 2021 • edited Loading

Remaining:

review-notebook-app bot commented Oct 27, 2021

codecov bot commented Oct 27, 2021 • edited Loading

Codecov Report

jbusecke commented Dec 7, 2021

zmoon commented Dec 7, 2021 • edited Loading

zmoon commented Dec 8, 2021

jbusecke commented Dec 8, 2021

jbusecke commented Dec 8, 2021

jbusecke left a comment

Choose a reason for hiding this comment

jbusecke Dec 8, 2021

Choose a reason for hiding this comment

zmoon Dec 8, 2021 • edited Loading

Choose a reason for hiding this comment

zmoon commented Dec 8, 2021 • edited Loading

zmoon commented Dec 8, 2021

jbusecke commented Dec 8, 2021

zmoon commented Dec 10, 2021

jbusecke commented Dec 15, 2021

zmoon commented Dec 15, 2021

jbusecke commented Dec 16, 2021

jbusecke commented Dec 16, 2021

zmoon commented Dec 16, 2021 • edited Loading

jbusecke commented Dec 16, 2021

zmoon commented Dec 16, 2021

zmoon commented Oct 27, 2021 •

edited

Loading

codecov bot commented Oct 27, 2021 •

edited

Loading

zmoon commented Dec 7, 2021 •

edited

Loading

zmoon Dec 8, 2021 •

edited

Loading

zmoon commented Dec 8, 2021 •

edited

Loading

zmoon commented Dec 16, 2021 •

edited

Loading