Include sample conf files

docs/conf.py

@@ -70,8 +70,10 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['_build', 'Thumbs.db',
-                    '.DS_Store', 'generated/cli-*', 'generated/conf-*']
+exclude_patterns = [
+    '_build', 'Thumbs.db', '.DS_Store',
+    'generated/cli-*.rst', 'generated/conf-*.rst'
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -300,6 +302,8 @@ class ConfLexer(RegexLexer):
     tokens = {
         'root': [
             (r'#.*?$', Comment.Single),
+            (r'\s+$', Whitespace),
+            (r'\s+', Whitespace),
             (r'(include)(\s+)(.+?)$', bygroups(Comment.Preproc, Whitespace, Name.Namespace)),
             (r'(map)(\s+)(\S+)(\s+)', bygroups(
                 Keyword.Declaration, Whitespace, String, Whitespace), 'action'),
@@ -522,18 +526,27 @@ def write_conf_docs(app, all_kitten_names):
     sc_role.warn_dangling = True
     sc_role.process_link = process_shortcut_link
 
+    def generate(all_options, name='kitty'):
+        from kitty.conf.definition import as_conf_file
+        from textwrap import indent
+        with open(f'generated/conf-{name}.rst', 'w', encoding='utf-8') as f:
+            print('.. highlight:: conf\n', file=f)
+            f.write(render_conf(name, all_options.values()))
+
+        with open(f'generated/conf-{name}-literal.rst', 'w', encoding='utf-8') as f:
+            print('.. code-block:: conf\n', file=f)
+            text = '\n'.join(as_conf_file(all_options.values()))
+            text = indent(text, '    ', lambda l: True)
+            print(text, file=f)
+
     from kitty.config_data import all_options
-    with open('generated/conf-kitty.rst', 'w', encoding='utf-8') as f:
-        print('.. highlight:: conf\n', file=f)
-        f.write(render_conf('kitty', all_options.values()))
+    generate(all_options)
 
     from kittens.runner import get_kitten_conf_docs
     for kitten in all_kitten_names:
         all_options = get_kitten_conf_docs(kitten)
         if all_options:
-            with open(f'generated/conf-kitten-{kitten}.rst', 'w', encoding='utf-8') as f:
-                print('.. highlight:: conf\n', file=f)
-                f.write(render_conf(kitten, all_options.values()))
+            generate(all_options, f'kitten-{kitten}')
 # }}}
 
 

docs/conf.rst

@@ -30,3 +30,11 @@ expanded, so :code:`${USER}.conf` becomes :file:`name.conf` if
 
 
 .. include:: /generated/conf-kitty.rst
+
+
+Sample kitty.conf
+^^^^^^^^^^^^^^^^^^^^^
+
+Below is a sample :file:`kitty.conf` with all default settings.
+
+.. include:: /generated/conf-kitty-literal.rst

docs/kittens/diff.rst

@@ -140,3 +140,11 @@ of code needed (the entire implementation is under 2000 lines of code).
 
 And fundamentally, it's kitty only because I wrote it for myself, and I am
 highly unlikely to use any other terminals :)
+
+
+Sample diff.conf
+-----------------
+
+Below is a sample :file:`diff.conf` with all default settings.
+
+.. include:: /generated/conf-kitten-diff-literal.rst

kitty/config_data.py

@@ -636,7 +636,7 @@ probably better off just hiding the titlebar with :opt:`macos_hide_titlebar`.
 '''))
 
 o('macos_hide_titlebar', False, long_text=_('''
-# Hide the kitty window's title bar on macOS.'''))
+Hide the kitty window's title bar on macOS.'''))
 
 o('macos_option_as_alt', True, long_text=_('''
 Use the option key as an alt key. With this set to no, kitty will use