Fix comments

helm-chart/images/binderhub/Dockerfile

@@ -22,8 +22,7 @@ COPY . /tmp/binderhub
 WORKDIR /tmp/binderhub
 
 # Build the binderhub python library into a wheel and save it to the ./dist
-# folder. Also build pycurl into a wheel as doing it requires curl-config and
-# gcc that aren't available in the slim version of the final stage.
+# folder. There are no pycurl wheels so we build our own in the build stage.
 RUN python setup.py bdist_wheel
 RUN pip wheel pycurl --wheel-dir ./dist
 

requirements.txt

@@ -1,12 +1,12 @@
 # About pycurl:
-# - pycurl is strongly recommended for performance but not strictly required by
-#   BinderHub.
-# - pycurl require both `curl-config` and `gcc` to be available when installing.
-# - The binderhub package require pycurl, but it is a dependency augmented to
-#   this files listed dependencies from within setup.py so that it can be
-#   either omitted as in our ReadTheDocs build that does code inspection of the
-#   binderhub package, or be installed in a separate build step as in the
-#   BinderHub docker image.
+# - pycurl is a dependency but not listed here, only in `setup.py`
+# - pycurl requires both `curl-config` and `gcc` to be available when installing
+#   it from source.
+# - the reason we do not list pycurl here is that it is not needed when our
+#   code is imported to generate the documentation and it is tricky to install
+#   in the ReadTheDocs build environment.
+# - instead we manually add pycurl to the list of dependencies in setup.py
+#   which is the list used when installing the binderhub package.
 docker
 escapism
 jinja2

setup.py

@@ -13,8 +13,7 @@
         l.strip() for l in f.readlines()
         if not l.strip().startswith('#')
     ]
-    # pycurl is augmented to requirements.txt as a dependency for the binderhub
-    # package for reasons explained within requirements.txt.
+    # manually add pycurl here, see comment in requirements.txt
     requirements.append("pycurl")
 
 with open(os.path.join(here, 'README.rst'), encoding="utf8") as f: