reintroduce conda env setup and docs

[bloomsa]

Per #1098, I am reintroducing some of the conda env pieces to assist with locally running EG and with debugging using an IDE. I specifically brought the targets for making and activating the conda environment but did not add that back to all of the other steps as it remains unnecessary for them.

I also updated the Contributor docs to reflect the additional step that can be used to aid local development

Resolves: #1098

[kevin-bates]

This looks good @bloomsa - thank you. I just had a couple of comments. Thanks for you help here.

[kevin-bates]

Looks good @bloomsa - thank you!

[kevin-bates]

I and others are seeing an issue with this PR and I apologize for merging this too soon (sigh). I don't really know how to resolve the following and I'm also wondering why @bloomsa didn't encounter this. Here are the results:

$ make ENV=test-env  env
conda env create --file requirements.yml --name test-env
Collecting package metadata (repodata.json): done
Solving environment: done


==> WARNING: A newer version of conda exists. <==
  current version: 4.12.0
  latest version: 4.13.0

Please update conda by running

    $ conda update -n base conda


Preparing transaction: done
Verifying transaction: done
Executing transaction: done
Installing pip dependencies: \ Ran pip subprocess with arguments:
['/opt/conda/envs/test-env/bin/python', '-m', 'pip', 'install', '-U', '-r', '/Users/kbates/repos/oss/jupyter/enterprise_gateway/condaenv.717zosga.requirements.txt']
Pip subprocess output:

Pip subprocess error:
ERROR: Directory '..' is not installable. Neither 'setup.py' nor 'pyproject.toml' found.

failed

CondaEnvException: Pip failed

make: [env] Error 1 (ignored)
conda env config vars set PYTHONPATH=/Users/kbates/repos/oss/jupyter/enterprise_gateway --name test-env

@blink1073 - we suspect this change to requirements.yml added in #1056 is the culprit, but don't understand what its purpose is. Could you please advise?

[blink1073]

It might be that it is installing from docs/requirement.yml from the top level directory. Perhaps it needs to be changed to . instead of ..

[kiersten-stokes]

Trying . does get things further along, but then I get the below error where conda is having trouble resolving the project requirement for jinja2>=3.1 (from pyproject.toml) with the doc requirement for jinja2<3.1.

Related, I see that jinja2<3.1 was required for the docs in order to prevent an ImportError (sphinx-doc/sphinx#10291). Looks like this is no longer an issue as of sphinx==4.0.2 (and 5.0.1 is the latest). I tested removing the jinja cap from doc-requirements.txt and creating a new env (with . in requirements.yml) and everything proceeded as expected!

Also, it may be worth pointing out that requirements.yml lists the jinja2 requirement as >=2.10 and pyproject.toml requires jinaj2>=3.1. This isn't a conflict, obviously, but feels relevant to mention. Happy to open a PR for any of the above if that's the appropriate direction to go.

The conflict is caused by:
    The user requested jinja2<3.1
    jupyter-enterprise-gateway 3.0.0.dev0 depends on jinja2>=3.1

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict


Pip subprocess error:
ERROR: Cannot install -r /Users/kierstenstokes/repos/enterprise_gateway/condaenv.urq965k2.requirements.txt (line 1) and jinja2<3.1 because these package versions have conflicting dependencies.
ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

failed

CondaEnvException: Pip failed

[kevin-bates]

Thanks @blink1073 and @kiersten-stokes. I'm afk for the weekend but, assuming I'm following things, sounds like the jinja dependency requires updating (along with the relative directory adjustment). Kiersten, if that works for you would you mind opening a pull request?
Thank you both!

[bloomsa]

Sorry about this!! 😢 I must not have fully cleaned my env up before trying to rebuild it.. Thanks for fixing it up @kiersten-stokes