[MRG] Improve docs on Dockerfile escape hatch

docs/source/conf.py

@@ -29,9 +29,9 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 templates_path = ["_templates"]
 extlinks = {
-    "issue": ("https://github.com/jupyterhub/repo2docker/issues/%s", "Issue #"),
-    "pr": ("https://github.com/jupyterhub/repo2docker/pull/%s", "PR #"),
-    "user": ("https://github.com/%s", "@"),
+    "issue": ("https://github.com/jupyterhub/repo2docker/issues/%s", "Issue #%s"),
+    "pr": ("https://github.com/jupyterhub/repo2docker/pull/%s", "PR #%s"),
+    "user": ("https://github.com/%s", "@%s"),
 }
 
 

docs/source/config_files.rst

@@ -240,10 +240,13 @@ In the majority of cases, providing your own Dockerfile is not necessary as the
 images provide core functionality, compact image sizes, and efficient builds. We recommend
 trying the other configuration files before deciding to use your own Dockerfile.
 
-With Dockerfiles, a regular Docker build will be performed.
+Try the ``--appendix`` :ref:`CLI flag <usage-cli>` as a last resort. If you
+still can't achieve your goals, you should create a Dockerfile from scratch to
+define your image.
 
 .. note::
-    If a Dockerfile is present, all other configuration files will be ignored.
+   With Dockerfiles, a regular Docker build will be performed. All other
+   configuration files will be ignored.
 
 See the `Advanced Binder Documentation <https://mybinder.readthedocs.io/en/latest/tutorials/dockerfile.html>`_ for
 best-practices with Dockerfiles.

docs/source/faq.rst

@@ -115,6 +115,9 @@ flag for each variable that you want to define.
 
 For example ``jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...``
 
+
+.. _faq-dockerfile-bootstrap:
+
 Can I use repo2docker to bootstrap my own Dockerfile?
 -----------------------------------------------------
 
@@ -189,3 +192,33 @@ tool called `source2image <https://github.com/openshift/source-to-image/>`_.
 This is an excellent open tool for containerization, but we
 ultimately decided that it did not fit the use-case we wanted to address. For more information,
 `here <https://github.com/yuvipanda/words/blob/fd096dd49d87e624acd8bdf6d13c0cecb930bb3f/content/post/why-not-s2i.md>`_ is a short blog post about the decision and the reasoning behind it.
+
+
+Where are my ``man`` pages?
+---------------------------
+
+The base image used by ``repo2docker`` is `Minimal Ubuntu
+<https://wiki.ubuntu.com/Minimal>`_ version 18. In Minimal Ubuntu, ``man``
+pages are disabled to reduce image size. If your use case is interactive
+computing or education, you may want to re-enable ``man`` pages. To do this,
+use the ``--appendix`` :ref:`CLI flag <usage-cli>` to pass in additional
+``Dockerfile`` instructions, for example:
+
+.. code-block:: dockerfile
+
+   # Re-enable man pages disabled in Ubuntu 18 minimal image
+   # https://wiki.ubuntu.com/Minimal
+   USER root
+   RUN yes | unminimize
+   # NOTE: $NB_PYTHON_PREFIX is the same as $CONDA_PREFIX at run-time.
+   # $CONDA_PREFIX isn't available in this context.
+   # NOTE: Prepending ensures a working path; if $MANPATH was previously empty,
+   # the trailing colon ensures that system paths are searched.
+   ENV MANPATH="${NB_PYTHON_PREFIX}/share/man:${MANPATH}"
+   RUN mandb
+
+   # Revert to default user
+   USER ${NB_USER}
+
+This appendix can be used by, for example, writing it to a file named
+``appendix`` and executing ``repo2docker --appendix "$(cat appendix)" .``.

docs/source/usage.rst

@@ -106,14 +106,21 @@ by ``repo2docker`` to see how to configure the build process.
    :ref:`configuration files <config-files>`.
 
 
+.. _usage-debugging-with-debug-and-no-build:
+
 Debugging repo2docker with ``--debug`` and ``--no-build``
 =========================================================
 
+.. warning::
+
+   This feature is *not* for bootstrapping a custom Dockerfile. Please see the
+   :ref:`relevant FAQ entry <faq-dockerfile-bootstrap>`.
+
 To debug the docker image being built, pass the ``--debug`` parameter:
 
-  .. code-block:: bash
+.. code-block:: bash
 
-     jupyter-repo2docker --debug https://github.com/norvig/pytudes
+   jupyter-repo2docker --debug https://github.com/norvig/pytudes
 
 This will print the generated ``Dockerfile``, build it, and run it.
 
@@ -122,10 +129,12 @@ pass ``--no-build`` to the commandline. This ``Dockerfile`` output
 is for **debugging purposes** of ``repo2docker`` only - it can not
 be used by docker directly.
 
-  .. code-block:: bash
+.. code-block:: bash
+
+   jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes
 
-     jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes
 
+.. _usage-cli:
 
 Command line API
 ================