Skip to main content

Authoring Documentation

This document provides guidelines for writing documentation for the DQX project.

Tech Stack​

The DQX documentation is built using Docusaurus, a modern static site generator.

Docusaurus is a Facebook open source project used by many open source projects to build their documentation websites.

We also use MDX to write markdown files that include JSX components. This allows us to write markdown files with embedded React components.

For styling, we use Tailwind CSS, a utility-first CSS framework for rapidly building custom designs.

API docs are generated using pydoc-markdown.

Writing Documentation​

Most of the documentation is written in markdown files with the .mdx extension. The markdown files are located in the docs directory of the DQX project.

Prerequisites​

Before you start writing documentation, make sure you have the following tools installed on your machine:

On macOS, you can install Node.js and Yarn using Homebrew:

brew install node
npm install --global yarn

Setup​

To set up the documentation locally, follow these steps:

  1. Clone the DQX repository
  2. Run:
make docs-install
make docs-build

Running the documentation locally​

To run the documentation locally, use the following command:

make docs-serve-dev

Checking search functionality​

Tip

We are using local search, which won't be available in the development server.

To check the search functionality, run the following command:

make docs-serve

Diagrams​

Use Mermaid for entity-relationship or flow diagrams. Wrap code in a mermaid code block:

```mermaid
erDiagram
    ENTITY_A ||--o{ ENTITY_B : "relationship"
```

See Table Schemas and Relationships for an example. Mermaid is enabled via @docusaurus/theme-mermaid (version must match @docusaurus/core).

Adding images​

To add images to your documentation, place the image files in the static/img directory.

To include an image in your markdown file, use the following syntax:

![Alt text](/img/image-name.png)
Tip

Images support zooming features out of the box.

For cases when images have transparent backgrounds, use the following syntax:

<div className='bg-gray-100 p-4 rounded-lg'>
  <img src={useBaseUrl('/img/dqx.png')} alt="DQX" />
</div>

This will add a gray background to the image and round the corners.

Linking pages​

It is strongly recommended to make all links absolute. By doing so we ensure that it's easy to move files without losing links inside them.

To add an absolute link, use this syntax:

[link text](/docs/folder/file_name)

Always start with /docs. The file extension .md or .mdx can be omitted.

To add an anchor to a specific heading, use this syntax:

[link with anchor](/docs/folder/file_name#anchor)

After writing docs, run this command:

make docs-build

It will throw an error on any unresolved link.

Tagging features with lifecycle stage and version​

Annotate a feature page or subsection with its lifecycle stage and the release version it relates to, using the components in src/components/FeatureTags.tsx.

Applying tags to feature documentation​

Import the tags you need, then place a <FeatureTags>row directly under the heading. Pass the tags as children with heading={false}.

import { FeatureLifecycleStage, AvailableSinceVersion, FeatureTags }
  from '@site/src/components/FeatureTags';

# My Feature

<FeatureTags>
  <AvailableSinceVersion version="0.14.0" heading={false} />
  <FeatureLifecycleStage stage="beta" heading={false} />
</FeatureTags>

Each tag also accepts heading (default true) for the rarer case of sitting inline next to heading text; inside a <FeatureTags> row, pass heading={false} so the badges render at their normal size.

Keep tags out of the heading line

Place tags in a <FeatureTags> row under the heading, not inside the # line. Docusaurus derives the browser tab title and sidebar label from the raw heading text. A tag left in the heading would leak the component markup into these elements.

Feature tagging conventions​

Any page, section, or subsection heading can be tagged. The following conventions are used for tagging feature documentation:

  • Untagged features represent generally-available functionality. If a version tag is missing, the feature has been available since before release version 0.9.0.
  • If a feature page is tagged, all untagged subheadings share the same version and lifecycle stage.
  • If any subheading is tagged, that capability has it own version and lifecycle stage which differs from the page-level version and lifecycle stage.
  • Sections with structural content, explanations, or examples should not be tagged.

Available feature tags​

The following components are available:

*<FeatureLifecycleStage stage="experimental | beta | ga | deprecated" /> — a status badge linked to the matching section of the Feature lifecycle reference. *<AvailableSinceVersion version="0.14.0" /> — "Available since v0.14.0", linked to that release's notes. *<DeprecatedInVersion version="0.16.0" replacement="the new_check function" /> — "Deprecated in v0.16.0", with an optional replacement named in the tooltip. *<FeatureTags> — the row container that places the tags on their own line under the heading.

Content alignment and structure of folders​

When writing documentation, make sure to align the content with the existing documentation.

The rule of thumb is:

  • Do not put any technical details in the main documentation.
  • All technical details should be kept in the /docs/dev/ section.

No need for:

  • Source code links
  • Deep technical details
  • Implementation details

Or any other details that are not necessary for the end-user.

API Documentation​

The API docs are generated in the docs/dqx/docs/reference/api directory.

To generate API docs, run the following command:

uv run --group docs pydoc-markdown

This is the same invocation that make docs-build and make docs-serve-dev run, so the recommended way is simply make docs-build. The command will generate the API documentation from the Python codebase using pydoc-markdown.

For best practices on writing docstrings, refer to this guidance.