Documentation Contributions

Contributing to the docs is one of the easiest and most helpful ways to help the project. Documentation changes require relatively little specialist knowledge apart from being familiar with how to use SQLFluff and the docs are read by a very wide range of people.

Documentation takes two forms:

1. Embedded documentation found in function and module docstrings.

2. The free-standing documentation which you’re reading now, and hosted at docs.sqlfluff.com (built using sphinx and ReadtheDocs).

The two are somewhat blurred by the use of autodoc (and some other custom integrations), where documentation is generated directly off docstrings within the codebase, for example the Rules Reference, CLI Reference and Dialects Reference. To understand more about how the custom integrations we use to generate these docs, see the generate-auto-docs.py file.

Docstrings

Embedded documentation of functions, classes and modules is most useful for developer-focussed documentation as it’s most accessible in the places which those developers are working: directly in the codebase. We enforce that docstrings are present and correctly formatted using the pydocstyle rules for ruff, which we have configured to enforce the google style of docstrings.

Sphinx Docs

The main documentation (which you’re reading now), is build using sphinx, and written using reStructuredText (files ending with .rst). The sphinx project offers a reStructuredText primer for people who are new to the syntax (and the SQLFluff project uses doc8 in the CI process to try and catch any issues early).

On top of those docs, there are a few areas worth highlighting for new (or returning) users, which are either specific to the SQLFluff project, or not particularly clear in the sphinx docs:

• reStructuredText is very similar to, but differs from (the somewhat more well known) Markdown syntax. Importantly:

  • *text with single asterisks* renders as italics. Use **double asterisks** for bold text.

  • code snippets are created using the :code:`...` directive, rather than just lone backticks (`...`) as found in most Markdown.

• To create links to other parts of the documentation (i.e. Cross-referencing), use either the :ref: syntax.

  • Docs for all the SQL dialects are auto generated with associated anchors to use for referencing. For example to link to the PostgreSQL dialect docs, you can use the :ref:`postgres_dialect_ref`. Replace the postgres portion with the name of the dialect you want to link to.

  • Docs for all the bundled rules and handled using a customer sphinx plugin, which means you can refer to them using their name or code: :sqlfluff:ref:`LT01` resolves to LT01 and :sqlfluff:ref:`layout.spacing` resolves to layout.spacing.

  • Docs for any of the python classes and modules handled using autodoc can be referenced as per their docs, so the sqlfluff.core.rules.base.BaseRule class can be referenced with :py:class:`sqlfluff.core.rules.base.BaseRule`. You can also use the ~ prefix (i.e. :py:class:`~sqlfluff.core.rules.base.BaseRule`) so that it just renders as BaseRule. See the docs for Cross-referencing for more details.