Repository: jupyterhub/jupyterhub

Issue:
Include Default Config Files and Documented CLI Options in docs
### Proposed change
Many people deploy this into containerized environments, and as such generating a config file to modify or running `jupyterhub --help-all` to get the options when starting the server is a time-consuming and non-trivial task depending on your environment. It would be great if the repo (or some referenced location) could host a default `jupyterhub_config.py` users could modify without having to create an environment in which to install, generate, and extract the file. Similarly, it'd be great if the docs for configuration would just list the options for starting the process rather than saying "run --help".


### Alternative options
As mentioned above, in interactive environments this is easy to deal with and a non-issue, but when writing a dockerfile, working on a thin client before deploying to a cluster that costs you money to access, etc. these are inconvenient, time-consuming, and potentially have a cost associated. Since these aren't exactly tall asks, I think this is pretty reasonable.


### Who would use this feature?
Anyone creating a configuration for their deployment as code who isn't setting it up interactively, which I have to imagine is most people.



Discussion:
Automatically including the output of `jupyterhub --generate-config` and `jupyterhub --help-all` as part of the docs build sounds like a good idea to me. We'll probably want to do some post-processing to convert some absolute paths like the cwd and home to e.g. `.` and `~` (or be fancy and define these as variables in the config file and use them appropriately)

Resolving patch:
diff --git a/docs/source/conf.py b/docs/source/conf.py
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -60,11 +60,65 @@
 import recommonmark
 from recommonmark.transform import AutoStructify
 
+# -- Config -------------------------------------------------------------
+from jupyterhub.app import JupyterHub
+from docutils import nodes
+from sphinx.directives.other import SphinxDirective
+from contextlib import redirect_stdout
+from io import StringIO
+
+# create a temp instance of JupyterHub just to get the output of the generate-config
+# and help --all commands.
+jupyterhub_app = JupyterHub()
+
+
+class ConfigDirective(SphinxDirective):
+    """Generate the configuration file output for use in the documentation."""
+
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self):
+        # The generated configuration file for this version
+        generated_config = jupyterhub_app.generate_config_file()
+        # post-process output
+        home_dir = os.environ['HOME']
+        generated_config = generated_config.replace(home_dir, '$HOME', 1)
+        par = nodes.literal_block(text=generated_config)
+        return [par]
+
+
+class HelpAllDirective(SphinxDirective):
+    """Print the output of jupyterhub help --all for use in the documentation."""
+
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self):
+        # The output of the help command for this version
+        buffer = StringIO()
+        with redirect_stdout(buffer):
+            jupyterhub_app.print_help('--help-all')
+        all_help = buffer.getvalue()
+        # post-process output
+        home_dir = os.environ['HOME']
+        all_help = all_help.replace(home_dir, '$HOME', 1)
+        par = nodes.literal_block(text=all_help)
+        return [par]
+
 
 def setup(app):
     app.add_config_value('recommonmark_config', {'enable_eval_rst': True}, True)
     app.add_css_file('custom.css')
     app.add_transform(AutoStructify)
+    app.add_directive('jupyterhub-generate-config', ConfigDirective)
+    app.add_directive('jupyterhub-help-all', HelpAllDirective)
 
 
 source_suffix = ['.rst', '.md']


Test patch: