Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve docs for load_macros_from_path #2743

Merged
merged 3 commits into from Feb 28, 2022
Merged

Improve docs for load_macros_from_path #2743

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
40b631f
Improve docs for "load_macros_from_path"
Feb 28, 2022
db28cea
Merge branch 'main' into bhart-issue_2740_improve_docs_for_load_macro…
barrywhart Feb 28, 2022
b0ca73e
Merge branch 'main' into bhart-issue_2740_improve_docs_for_load_macro…
barrywhart Feb 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
32 changes: 18 additions & 14 deletions docs/source/configuration.rst
View file
Open in desktop
Expand Up @@ -409,21 +409,25 @@ loaded from files or folders. This is specified in the config file:
[sqlfluff:templater:jinja]
load_macros_from_path = my_macros

`load_macros_from_path` is a comma-separated list of files or folders. SQLFluff
will load macros from any :code:`.sql` file found in the specified locations.
Locations are *relative to the config file*. For example, if the config file
above was found at :code:`/home/my_project/.sqlfluff` then SQLFluff will look
for macros in the folder :code:`/home/my_project/my_macros/` (but not
subfolders). Alternatively, the path can also be a :code:`.sql` itself. Any
macros defined in the config will always take precedence over a macro defined
in the path.

**Note:** The `load_macros_from_path` also defines the search path for Jinja
[include](https://jinja.palletsprojects.com/en/3.0.x/templates/#include) or
[import](https://jinja.palletsprojects.com/en/3.0.x/templates/#import).
``load_macros_from_path`` is a comma-separated list of :code:`.sql` files or
folders. Locations are *relative to the config file*. For example, if the
config file above was found at :code:`/home/my_project/.sqlfluff`, then
SQLFluff will look for macros in the folder :code:`/home/my_project/my_macros/`
(but not subfolders). Any macros defined in the config will always take
precedence over a macro defined in the path.

* :code:`.sql` files: Macros in these files are available in every :code:`.sql`
file without requiring a Jinja :code:`include` or :code:`import`.
* Folders: To use macros from the :code:`.sql` files in folders, use Jinja
:code:`include` or :code:`import` as explained below.

**Note:** The :code:`load_macros_from_path` setting also defines the search
path for Jinja
`include <https://jinja.palletsprojects.com/en/3.0.x/templates/#include>`_ or
`import <https://jinja.palletsprojects.com/en/3.0.x/templates/#import>`_.
Unlike with macros (as noted above), subdirectories are supported. For example,
if `load_macros_from_path` is set to `my_macros`, and there is a file
`my_macros/subdir/my_file.sql`, you can do:
if :code:`load_macros_from_path` is set to :code:`my_macros`, and there is a
file :code:`my_macros/subdir/my_file.sql`, you can do:

.. code-block:: jinja

Expand Down