Add installation instructions to the documentation about xinvert HOT 15 CLOSED

Sorry @NoraLoose, I know these two issues are different. The second one is not too hard to fix. I just prefer to having both issues fixed at the same time, as they are all related to installation here.

from xinvert.

Also, it would be great if you could remind the user (in installation instructions in README and doc) how to create the conda environment necessary to run the notebooks in the documentation.

cd xinvert
conda env create -f environment.yml 

from xinvert.

You could also consider adding ipykernel to the list of packages in environment.yml so people can use the conda environment on the jupyter hub to run the notebooks. That's up to you!

from xinvert.

Further necessary packages to run the jupyter notebooks that could be added to environment.yml are:

• proplot
• cartopy
• ?

from xinvert.

Thanks @NoraLoose for these helpful suggestions.

It would be helpful to have the installation instructions not only in the README, but also in the documentation.

Forgot about this. I should add the instructions these days to the documentation.

Also, it would be great if you could remind the user (in installation instructions in README and doc) how to create the conda environment necessary to run the notebooks in the documentation.

I guess I am not familiar with the jupyer-hub things. So I am not quite sure how to run the notebooks by other people. Could you please send me a tutorial on the jupyter-hub concept or practice, so that I can figure out a full list of pkgs needed in environment.yml?

from xinvert.

Sorry, you don't really need the jupyter hub to run the notebooks. If you don't use the jupyter hub, I assume you follow the following workflow:

1. Activate some conda environment.
2. Start jupyter.
3. Run the notebooks in the documentation.

The question is what packages are in the conda environment from 1)? There must be more packages than in environment.yml, because you need plotting packages like proplot, cartopy, etc.

You could either add these packages to environment.yml, or make a second environment file, e.g., environment-notebooks.yml, which includes all packages from environment.yml plus the plotting packages that are only needed for the notebooks. Does this make sense?

from xinvert.

Thanks @NoraLoose. Don't worry, I really want to learn some new things. I could add those pkgs I remember. But sometimes I may miss one or two (actually I didn't remember why there is an environment.yml in the folder). So the best practice is to run it in a new environment (like jupyter hub). Then I know if I miss any pkg or not. Maybe all the imported pkgs in the notebooks should be OK?

from xinvert.

Yes, exactly. I would execute the following steps:

• Add all packages that the notebooks use (e.g., proplot, cartopy) to your environment.yml file
• Create the conda environment:

cd xinvert
conda env create -f environment.yml 

• Activate your conda environment

conda activate xinvert

• Start jupyter notebook from this conda environment (see for example this documentation for jupyter notebooks)
• Run the notebooks and see if they execute; if not you need to add more packages to environment.yaml

from xinvert.

Hi @NoraLoose, I really want to add a installation from conda. I've sent a PR here weeks ago, but no response at all. Just want to know if I missed something, as this is the first time I do this. Do I need to ask someone to review the PR?

from xinvert.

Hi @miniufo! There are two, distinct conda-related issues:

1. Being able to install xinvert from conda. That is the PR you opened at conda-forge/staged-recipes#23082
2. Providing an environment.yaml file so that users of xinvert can create a conda environment that has all the packages that are necessary to run the notebooks.

I was referring to the second point.

See for example https://gcm-filters.readthedocs.io/en/latest/installation.html#installation-from-conda-forge versus https://gcm-filters.readthedocs.io/en/latest/installation.html#how-to-run-the-example-notebooks as an example for the differences between 1. and 2.

from xinvert.

Hi @NoraLoose, I've added the installation page to the docs at here (for conda, I add not available yet). The environment.yml is also updated and tested by creating a new env so that the notebooks can be executed. Please check these again. Thank you very much.

from xinvert.

I've added the installation page to the docs at here (for conda, I add not available yet)

I would delete the section about installation from conda. If a user does not read carefully, they may think conda installation is available. You can re-add this to the documentation once installation from conda is working.

Instead, I would add a section on how to create the conda environment to run the example notebooks, similarly to what is done here.

I just tried your new environment.yml and execute all notebooks. I get the error

ModuleNotFoundError: No module named 'xcontour'

from xinvert.

Hi, @NoraLoose I've removed the part of conda install from both README and docs page.

The dependence of xcontour is a bit complicated. It is another package I've written here. So the example of reference state, which is newly added, depends on xcontour to prepare the forcing (actually preparing the forcing data is not the core part of xinvert). This is not necessary for other examples. So far, I don't have any plan to get xcontour released as a conda package, so it is not possible to add this to conda dependency. Do you have any suggestion? I really like this example to remain in the problem list.

By the way, do you know how long my conda-recipe PR will be reviewed and merged? Since I am doing this first time, I've no idea about this. It's been a month now.

from xinvert.

By the way, do you know how long my conda-forge/staged-recipes#23082 will be reviewed and merged? Since I am doing this first time, I've no idea about this. It's been a month now.

Sorry, I'm not sure either.

Instead, I would add a section on how to create the conda environment to run the example notebooks, similarly to what is done here.

Are you still planning on adding these instructions to the README and docs?

from xinvert.

Are you still planning on adding these instructions to the README and docs?

Oops, I forgot to add this part to the docs. Now it is fixed at here

from xinvert.