Fix all warnings (but 2) when doing make html

[mwouts]

Currently when I run

cd docs
conda env create --file environment.yml
conda activate kernel_gateway_docs
make html

I get this output

sphinx-build -b html -d build/doctrees  -n source build/html
Running Sphinx v3.2.1
making output directory... done
WARNING: html_static_path entry '_static' does not exist
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
/home/marc/miniconda3/envs/kernel_gateway_docs/lib/python3.5/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document
  warn("Container node skipped: type={0}".format(mdnode.t))
reading sources... [100%] websocket-mode                                        
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] websocket-mode                                         
/home/marc/GitHub/kernel_gateway/docs/source/devinstall.md:51: WARNING: None:any reference target not found: http-mode.html
/home/marc/GitHub/kernel_gateway/docs/source/features.md:5: WARNING: None:any reference target not found: websocket-mode.html
/home/marc/GitHub/kernel_gateway/docs/source/features.md:8: WARNING: None:any reference target not found: http-mode.html
/home/marc/GitHub/kernel_gateway/docs/source/features.md:20: WARNING: None:any reference target not found: http-mode.html
/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:39: WARNING: None:any reference target not found: _modules/kernel_gateway/jupyter_websocket.html
/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:39: WARNING: None:any reference target not found: _modules/kernel_gateway/notebook_http.html
/home/marc/GitHub/kernel_gateway/docs/source/uses.md:13: WARNING: None:any reference target not found: http-mode.html
generating indices...  genindexdone
writing additional pages...  searchdone
copying images... [100%] images/kg_basic.png                                    
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 8 warnings.

The HTML pages are in build/html.

Build finished. The HTML pages are in build/html.

With this PR, the output is, instead:

sphinx-build -b html -d build/doctrees  -n source build/html
Running Sphinx v3.2.1
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
/home/marc/miniconda3/envs/kernel_gateway_docs/lib/python3.5/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document
  warn("Container node skipped: type={0}".format(mdnode.t))
reading sources... [100%] websocket-mode                                                                                           
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] websocket-mode                                                                                            
/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:39: WARNING: None:any reference target not found: _modules/kernel_gateway/jupyter_websocket.html
/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:39: WARNING: None:any reference target not found: _modules/kernel_gateway/notebook_http.html
generating indices...  genindexdone
writing additional pages...  searchdone
copying images... [100%] images/kg_basic.png                                                                                       
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 2 warnings.

The HTML pages are in build/html.

Build finished. The HTML pages are in build/html.

For the two remaining warnings I assume they should point out to the documentation for the jupyter_websocket or notebook_http modules, but ATM I don't know how to generate that documentation.

[kevin-bates]

Hi Marc - yeah, there's something happening with the readthedocs builds. Here are the steps RTD performs (for a build that is currently failing)...

1. git clone --no-single-branch --depth 50 https://github.com/jupyter/kernel_gateway .
2. git checkout --force origin/master
3. git clean -d -f -f
4. conda env create --quiet --name latest --file docs/environment.yml
5. /home/docs/checkouts/readthedocs.org/user_builds/jupyter-kernel-gateway/conda/latest/bin/python -m pip install -U --no-cache-dir --use-feature 2020-resolver recommonmark readthedocs-sphinx-ext (when attempting locally the path to path should equate to where you're latest env was installed)

I am unable to reproduce the issue in the failing build, which is this...

Usage:   
  /home/docs/checkouts/readthedocs.org/user_builds/jupyter-kernel-gateway/conda/latest/bin/python -m pip install [options] <requirement specifier> [package-index-options] ...
  /home/docs/checkouts/readthedocs.org/user_builds/jupyter-kernel-gateway/conda/latest/bin/python -m pip install [options] -r <requirements file> [package-index-options] ...
  /home/docs/checkouts/readthedocs.org/user_builds/jupyter-kernel-gateway/conda/latest/bin/python -m pip install [options] [-e] <vcs project url> ...
  /home/docs/checkouts/readthedocs.org/user_builds/jupyter-kernel-gateway/conda/latest/bin/python -m pip install [options] [-e] <local project path> ...
  /home/docs/checkouts/readthedocs.org/user_builds/jupyter-kernel-gateway/conda/latest/bin/python -m pip install [options] <archive url/path> ...

no such option: --use-feature

which implies an older pip. When I run, I get pip 20.2.3, which seems current enough. However, I do see python 3.5 in use and we should update the python version in environment.yml. I'm thinking we should probably move to 3.7 and figure we might as well use this PR to also enact that change.

Since I don't have maintainer rights on the JKG RTD, I'm unable to do much poking around there.

@parente or @willingc - could one of you please add me to the RTD maintainers list so I can trigger/maintain builds? Thanks.

[kevin-bates]

Hi Marc - thanks for your help here. Per my latest comment, could you please include a version increment of the python version in environment.yml as well.

Also, I'm not sure how to address this warning message I see when running locally...

Warning: you have pip-installed dependencies in your environment file, but you do not list pip itself as one of your conda dependencies.  Conda may not use the correct pip to install your packages, and they may end up in the wrong place.  Please add an explicit pip dependency.  I'm adding one for you, but still nagging you.

This occurs on the step to create the RTD conda env: conda env create --quiet --name latest --file docs/environment.yml. If you have an idea for how to address that, could you please give it a shot via the PR as well? Thanks.

[willingc]

@kevin-bates Added.

@mwouts, Kevin: I would recommend moving away from recommonmark. Use myst_parser instead.

[willingc]

Also @mwouts, if you will be maintaining these docs, I am happy to add you to the RTD maintainers. Just let me know.

[mwouts]

Hi Kevin, Carol,

Per my latest comment, could you please include a version increment of the python version

Sure!

Also, I'm not sure how to address this warning message I see when running locally

Warning: you have pip-installed dependencies in your environment file, but you do not list pip itself as one of your conda dependencies.  Conda may not use the correct pip to install your packages, and they may end up in the wrong place.  Please add an explicit pip dependency.  I'm adding one for you, but still nagging you.

Oh I've seen that one many times... you just need to list pip among the dependencies, like in the commit cf6c021 above.

Also, in 7ef35b9 I have added the additional packages that appear in the failing step of the build you linked above, hopefully this will let you remove that step from RTD.

I would recommend moving away from recommonmark. Use myst_parser instead.

Oh sure... I can give it a try - I'll open another PR if it works well.

Also @mwouts, if you will be maintaining these docs, I am happy to add you to the RTD maintainers

Thank you Carol. Well I don't promise big thinks, but I'll be happy to help!

[willingc]

@mwouts Thanks for the corrections. Going to merge.

Happy to add you as a maintainer on RTD. What is your RTD user name? mwouts didn't work for me.

[kevin-bates]

Thank you Marc and Carol!

[mwouts]

Awesome! And now the RTD site works, that's great. Carol, my user name on RTD is marc.wouts. Thanks!

[willingc]

Added @mwouts :D Thanks!