Repository: jupyterhub/jupyterhub
Pull request: Add Configuration Reference section to docs
Closes #3066 

Tried a naive approach to capture the output of `jupyterhub --generate-config` and `jupyterhub --help-all` commands, and display in the generated documentation.

It worked, but as I am still learning Sphinx and how to use/extend it, there may be other better alternatives? For example, I got similar behaviour with the extensions `sphinxcontrib-programoutput` and with `sphinx-autorun`.

At $work, there is a project using Sphinx extensions, and we found that some times extensions are not compatible with the latest version of sphinx, which may hold back the project from updating sphinx. That's why I decided on a directive :+1: 

Happy to move to another section, or update as necessary. One thing bothering me is trying to find the properties in the middle of the comments. Although I normally search the output for things like "ssl", or "proxy", etc.

Cheers
Bruno

Problem statement:
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.

Hints from issue 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)

Commit message: Add Configuration Reference

Patch to review:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 64e4939a5d..e0eb3bb914 100644
--- 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']
diff --git a/docs/source/reference/config-reference.rst b/docs/source/reference/config-reference.rst
new file mode 100644
index 0000000000..5b3c2acb2d
--- /dev/null
+++ b/docs/source/reference/config-reference.rst
@@ -0,0 +1,30 @@
+==============================
+Configuration Reference
+==============================
+
+.. important::
+
+    Make sure the version of JupyterHub for this documentation matches your
+    installation version, as the output of this command may change between versions.
+
+JupyterHub configuration
+------------------------
+
+As explained in the `Configuration Basics <../getting-started/config-basics.html#generate-a-default-config-file>`_
+section, the ``jupyterhub-config.py`` can be automatically generated via
+
+    .. code-block:: bash
+
+        jupyterhub --generate-config
+
+
+The following contains the output of that command for reference.
+
+.. jupyterhub-generate-config::
+
+JupyterHub help command output
+------------------------------
+
+This section contains the output of the command ``jupyterhub --help-all``.
+
+.. jupyterhub-help-all::
diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst
index b900025de8..4008a7231f 100644
--- a/docs/source/reference/index.rst
+++ b/docs/source/reference/index.rst
@@ -24,3 +24,4 @@ what happens under-the-hood when you deploy and configure your JupyterHub.
    config-ghoauth
    config-proxy
    config-sudo
+   config-reference


Code review comments:
diff_hunk: @@ -0,0 +1,30 @@
+==============================
+Configuration Reference
+==============================
+
+.. important::
+
+    Make sure the version of JupyterHub for this documentation matches your
+    installation version, as the output of this command may change between versions.
+
+JupyterHub configuration
+------------------------
+
+As explained in the `Configuration Basics <../getting-started/config-basics.html#generate-a-default-config-file>`_
+section, the ``jupyterhub-config.py`` can be automatically generated via
path: docs/source/reference/config-reference.rst
text: @user1:
```suggestion
section, the ``jupyterhub_config.py`` can be automatically generated via
```