Synchronize common aspects of developer guides

[droumis]

There are currently 3 or 4 primary places that new contributors can go for basic HoloViz project set-up instructions:

• hvPlot developer guide
• Panel developer guide (HoloViews points here too)
• HoloViz contributing guide
• HoloViz contributing guide > Operating guide > Pyctdev

I think these instructions should be synchronized whenever possible, and only diverge if there is a package-specific reason to do so.

Here are the primary steps from each source listed above:

Panel:

conda install -c pyviz "pyctdev>0.5.0"
doit env_create -c pyviz/label/dev -c conda-forge --name=panel_dev --python=3.9
conda activate panel_dev
doit develop_install -c pyviz/label/dev -c conda-forge -c bokeh -o build -o tests -o recommended 
pre-commit install

hvPlot:

conda install mamba -c conda-forge
conda create -n hvplot_dev
conda activate hvplot_dev
conda config --env --append channels pyviz/label/dev --append channels conda-forge
conda config --env --remove channels defaults
mamba install python=3.x pyctdev
doit develop_install -o tests -o examples --conda-mode mamba
pre-commit install

HoloViz Contributing:

conda install -c pyviz/label/dev "pyctdev>0.5.0"
doit env_create -c channel1 -c channel2 --name=dev-env --python=3.x
conda activate dev-env
doit develop_install -c pyviz/label/dev -c conda-forge -o tests -o examples

HoloViz Operating > Pyctdev:

conda install -c pyviz/label/dev pyctdev
doit env_create -c pyviz -c conda-forge --python=3.8 --name=my_dev_env
conda activate my_dev_env
doit -c pyviz -c conda-forge develop_install -o tests -o examples

The HoloViz Contributing guide contains a critical tip:

The reference sources to find out which commands to run to install the correct dependencies and to execute the tests and other tasks are the Github Actions Workflows files that you can find in the .github folder of each repository.

And while that is quite important, the CI files can be quite confusing for non-core HoloViz contributors, as they have to cherry-pick which commands to run locally, and there are some which are dangerous to run locally (conda config --remove channels defaults)

Also, I think the nbsite section on the HoloViz Operating guide might be the only source of guidance on building the docs, other than the CI workflows.

---

What would be a common set of basic instructions?

Should we recommend that people use pyviz or the pyviz/label/dev channel?

Should we recommend the use of mamba?

Should we stop suggesting the use of pyctdev?

[maximlt]

Somehow I missed this message, which happens to be quite related to the issue I opened on pyctdev the day after this one was posted holoviz-dev/pyctdev#104.

My take on this at the moment:

• I am in favor of recommending contributors to install their dependencies with pip. I think that now pip has a dependency solver (albeit I believe not as sophisticated as conda's) people are less likely to get into trouble, notwithstanding the fact that most packages are now distributed as wheels. We could still indicate that if they want to use conda they can do it via pyctdev, pyctdev providing this very nice feature of collecting the dependencies that need to be installed. So we'd recommend something like python -m venv .venv, source activate .venv/bin/activate and pip install -e [tests,examples].
• Whatever we suggest, it must be tested on CI.
• Whatever we suggest, someone must be in charge of maintaining that documentation up-to-date. Now the HoloViz group has more contributors, I think we should be able to distribute that job pretty well without it becoming a burden.
• I think we should focus first on improving the dev instructions for testing as it's the most common task contributors may be willing to tackle. Next would be building the docs. I think building packages is pretty rare, that's low priority.