Include "config template" in docs (#7355)

- Extract data from file
- Add in "collapse" section
- Cleanup template file

docs/docs/start/config.md

@@ -22,7 +22,11 @@ The InvenTree server tries to locate the `config.yaml` configuration file on sta
 !!! tip "Config File Location"
     When the InvenTree server boots, it will report the location where it expects to find the configuration file
 
-The configuration file *template* can be found on [GitHub]({{ sourcefile("src/backend/InvenTree/config_template.yaml") }})
+#### Configuration File Template
+
+The configuration file *template* can be found on [GitHub]({{ sourcefile("src/backend/InvenTree/config_template.yaml") }}), and is shown below:
+
+{{ includefile("src/backend/InvenTree/config_template.yaml", "Configuration File Template", format="yaml") }}
 
 !!! info "Template File"
     The default configuration file (as defined by the template linked above) will be copied to the specified configuration file location on first run, if a configuration file is not found in that location.

docs/main.py

@@ -167,27 +167,37 @@ def define_env(env):
         return assets
 
     @env.macro
-    def templatefile(filename):
+    def includefile(filename: str, title: str, format: str = ''):
-        """Include code for a provided template file."""
+        """Include a file in the documentation, in a 'collapse' block.
+
+        Arguments:
+            - filename: The name of the file to include (relative to the top-level directory)
+            - title:
+        """
         here = os.path.dirname(__file__)
-        template_dir = os.path.join(
+        path = os.path.join(here, '..', filename)
-            here, '..', 'src', 'backend', 'InvenTree', 'report', 'templates'
+        path = os.path.abspath(path)
-        )
-        template_file = os.path.join(template_dir, filename)
-        template_file = os.path.abspath(template_file)
 
-        basename = os.path.basename(filename)
+        if not os.path.exists(path):
+            raise FileNotFoundError(f'Required file {path} does not exist.')
 
-        if not os.path.exists(template_file):
+        with open(path, 'r') as f:
-            raise FileNotFoundError(f'Report template file {filename} does not exist.')
-
-        with open(template_file, 'r') as f:
             content = f.read()
 
-        data = f'??? abstract "Template: {basename}"\n\n'
+        data = f'??? abstract "{title}"\n\n'
-        data += '    ```html\n'
+        data += f'    ```{format}\n'
         data += textwrap.indent(content, '    ')
         data += '\n\n'
         data += '    ```\n\n'
 
         return data
+
+    @env.macro
+    def templatefile(filename):
+        """Include code for a provided template file."""
+        base = os.path.basename(filename)
+        fn = os.path.join(
+            'src', 'backend', 'InvenTree', 'report', 'templates', filename
+        )
+
+        return includefile(fn, f'Template: {base}', format='html')

src/backend/InvenTree/config_template.yaml

@@ -1,3 +1,6 @@
+# InvenTree Configuration Template
+# Ref: https://docs.inventree.org/en/stable/start/config/
+# Note: Environment variables take precedence over values set in this file
 
 # Secret key for backend
 # Use the environment variable INVENTREE_SECRET_KEY_FILE
@@ -5,16 +8,10 @@
 
 # Database backend selection - Configure backend database settings
 # Documentation: https://docs.inventree.org/en/latest/start/config/
-
 # Note: Database configuration options can also be specified from environmental variables,
 #       with the prefix INVENTREE_DB_
 #       e.g INVENTREE_DB_NAME / INVENTREE_DB_USER / INVENTREE_DB_PASSWORD
 database:
-  # Uncomment (and edit) one of the database configurations below,
-  # or specify database options using environment variables
-
-  # Refer to the django documentation for full list of options
-
   # --- Available options: ---
   # ENGINE: Database engine. Selection from:
   #         - mysql
@@ -26,65 +23,29 @@ database:
   # HOST: Database host address (if required)
   # PORT: Database host port (if required)
 
-  # --- Database settings ---
+# Set debug to False to run in production mode, or use the environment variable INVENTREE_DEBUG
-  #ENGINE: sampleengine
-  #NAME: '/path/to/database'
-  #USER: sampleuser
-  #PASSWORD: samplepassword
-  #HOST: samplehost
-  #PORT: 123456
-
-  # --- Example Configuration - MySQL ---
-  #ENGINE: mysql
-  #NAME: inventree
-  #USER: inventree
-  #PASSWORD: inventree_password
-  #HOST: 'localhost'
-  #PORT: '3306'
-
-  # --- Example Configuration - Postgresql ---
-  #ENGINE: postgresql
-  #NAME: inventree
-  #USER: inventree
-  #PASSWORD: inventree_password
-  #HOST: 'localhost'
-  #PORT: '5432'
-
-  # --- Example Configuration - sqlite3 ---
-  # ENGINE: sqlite3
-  # NAME: '/home/inventree/database.sqlite3'
-
-# Set debug to False to run in production mode
-# Use the environment variable INVENTREE_DEBUG
 debug: True
 
-# Set to False to disable the admin interface (default = True)
+# Set to False to disable the admin interfac, or use the environment variable INVENTREE_ADMIN_ENABLED
-# Or, use the environment variable INVENTREE_ADMIN_ENABLED
 #admin_enabled: True
 
-# Set the admin URL (default is 'admin')
+# Set the admin URL, or use the environment variable INVENTREE_ADMIN_URL
-# Or, use the environment variable INVENTREE_ADMIN_URL
 #admin_url: 'admin'
 
-# Configure the system logging level
+# Configure the system logging level (or use environment variable INVENTREE_LOG_LEVEL)
-# Use environment variable INVENTREE_LOG_LEVEL
 # Options: DEBUG / INFO / WARNING / ERROR / CRITICAL
 log_level: WARNING
 
-# Enable database-level logging
+# Enable database-level logging, or use the environment variable INVENTREE_DB_LOGGING
-# Use the environment variable INVENTREE_DB_LOGGING
 db_logging: False
 
-# Select default system language (default is 'en-us')
+# Select default system language , or use the environment variable INVENTREE_LANGUAGE
-# Use the environment variable INVENTREE_LANGUAGE
 language: en-us
 
-# System time-zone (default is UTC)
+# System time-zone (default is UTC). Reference: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-# Reference: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 timezone: UTC
 
-# Base URL for the InvenTree server
+# Base URL for the InvenTree server (or use the environment variable INVENTREE_SITE_URL)
-# Use the environment variable INVENTREE_SITE_URL
 # site_url: 'http://localhost:8000'
 
 # Base currency code (or use env var INVENTREE_BASE_CURRENCY)
@@ -149,15 +110,13 @@ sentry_enabled: False
 #  resources:
 #    CUSTOM_KEY: 'CUSTOM_VALUE'
 
-# Set this variable to True to enable InvenTree Plugins
+# Set this variable to True to enable InvenTree Plugins, or use the environment variable INVENTREE_PLUGINS_ENABLED
-# Alternatively, use the environment variable INVENTREE_PLUGINS_ENABLED
 plugins_enabled: False
 #plugin_noinstall: True
 #plugin_file: '/path/to/plugins.txt'
 #plugin_dir: '/path/to/plugins/'
 
-# Set this variable to True to enable auto-migrations
+# Set this variable to True to enable auto-migrations, or use the environment variable INVENTREE_AUTO_UPDATE
-# Alternatively, use the environment variable INVENTREE_AUTO_UPDATE
 auto_update: False
 
 # Allowed hosts (see ALLOWED_HOSTS in Django settings documentation)
@@ -248,56 +207,13 @@ remote_login_header: HTTP_REMOTE_USER
 #   github:
 #     VERIFIED_EMAIL: true
 
-# Add LDAP support
+# Add LDAP support (refer to the documentation for available options)
-# ldap:
+# Ref: https://docs.inventree.org/en/stable/start/advanced/#ldap
-#   enabled: false
+ldap:
-#   debug: false  # enable debug mode to troubleshoot ldap configuration
+  enabled: false
-#   server_uri: ldaps://example.org
-#   bind_dn: cn=admin,dc=example,dc=org
-#   bind_password: admin_password
-#   search_base_dn: cn=Users,dc=example,dc=org
-
-#   # enable TLS encryption over the standard LDAP port,
-#   # see: https://django-auth-ldap.readthedocs.io/en/latest/reference.html#auth-ldap-start-tls
-#   # start_tls: false
-
-#   # uncomment if you want to use direct bind, bind_dn and bin_password is not necessary then
-#   # user_dn_template: "uid=%(user)s,dc=example,dc=org"
-
-#   # uncomment to set advanced global options, see https://www.python-ldap.org/en/latest/reference/ldap.html#ldap-options
-#   # for all available options (keys and values starting with OPT_ get automatically converted to python-ldap keys)
-#   # global_options:
-#   #   OPT_X_TLS_REQUIRE_CERT: OPT_X_TLS_NEVER
-#   #   OPT_X_TLS_CACERTFILE: /opt/inventree/ldapca.pem
-
-#   # uncomment for advanced filter search, default: uid=%(user)s
-#   # search_filter_str:
-
-#   # uncomment for advanced user attribute mapping (in the format <InvenTree attribute>: <LDAP attribute>)
-#   # user_attr_map:
-#   #   first_name: givenName
-#   #   last_name: sn
-#   #   email: mail
-
-#   # always update the user on each login, default: true
-#   # always_update_user: true
-
-#   # cache timeout to reduce traffic with LDAP server, default: 3600 (1h)
-#   # cache_timeout: 3600
-
-#   # LDAP group support
-#   # group_search: ou=groups,dc=example,dc=com
-#   # require_group: cn=inventree_allow,ou=groups,dc=example,dc=com
-#   # deny_group: cn=inventree_deny,ou=groups,dc=example,dc=com
-#   # Set staff/superuser flag based on LDAP group membership
-#   # user_flags_by_group:
-#   #   is_staff: cn=inventree_staff,ou=groups,dc=example,dc=com
-#   #   is_superuser: cn=inventree_superuser,ou=groups,dc=example,dc=com
 
 # Customization options
-# Add custom messages to the login page or main interface navbar or exchange the logo
+# Ref: https://docs.inventree.org/en/stable/start/config/#customization-options
-# Use environment variable INVENTREE_CUSTOMIZE or INVENTREE_CUSTOM_LOGO
-# Logo and splash paths and filenames must be relative to the static_root directory
 # customize:
 #   login_message: InvenTree demo instance - <a href='https://inventree.org/demo.html'> Click here for login details</a>
 #   navbar_message: <h6>InvenTree demo mode <a href='https://inventree.org/demo.html'><span class='fas fa-info-circle'></span></a></h6>