Skip to content

Documentation (How To)

Where do I find this documentation

In the Gitlab repository there is a docs repository. All documentation you see on this page has been built from that.

This means that if you want an offline version of this documentation, this is where you can find it.

How do I change this documentation

You can simply create an issue, under the AI Issue queue. Then you do a MR with your changes and if they make sense we will merge them and they will show up.

For exact instructions see Contribute Documentation.

How do I test the changes locally

The documentation uses mkdocs and the material theme, so you can install with:

pip install mkdocs mike mkdocs-material mkdocs-include-markdown-plugin mkdocs-git-revision-date-localized-plugin mkdocs-glightbox

Then you can run mkdocs serve in the root directory of the AI module and it will be available under http://localhost:8000 by default.

My changes only apply for specific versions

Just make the MR to the latest version it applies to, and then you can tag the issue as "Backport to version x.x.x" and the maintainer that merges it will make sure it shows up on all the different documentations.

What should go into this documentation

In general it's quite broad - of course anything that affects AI and its submodules, but also big stroke documentation for Providers and AI Agents.

If you contribute to a Provider and want to promote it or write installation instructions, feel free to push it under the providers directory.

Best practices for images and diagrams

To keep the repository as lean as possible and ensure easy contributions for everyone (especially those in countries with limited internet bandwidth), we have specific guidelines for images and diagrams.

Images

Do not store images directly in the repository. Instead, follow these steps:

  1. Host images externally: All images should be stored on the GitLab Wiki for the AI project. Since it is on the same parent domain, hotlinking is possible and preferred.
  2. Use absolute URLs: Link to your images using their full URL from the GitLab wiki.
  3. Avoid relative paths: Never use relative paths to image files within the repository.

Diagrams and Charts

Instead of using static images for diagrams or charts, we use Mermaid. Mermaid allows you to create diagrams using text-based definitions which are:

  • Versionable: Changes can be tracked via Git.
  • Lightweight: No heavy binary files in the repository.
  • Easy to contribute: Anyone can update a diagram directly in the Markdown file without needing image editing tools.

Example of a Mermaid diagram:

graph TD;
    A[User Request]-->B[AI Module];
    B-->C{Provider};
    C-->D[OpenAI];
    C-->E[Anthropic];

How do you switch the default version (for Maintainers)

Maintainers with push rights can make a version the default for https://project.pages.drupalcode.org/ai/. The redirect on /ai/ is only changed by mike set-default, not by CI or aliases.

Example for 3.1.x:

  1. pip install mike mkdocs mkdocs-material mkdocs-include-markdown-plugin mkdocs-git-revision-date-localized-plugin mkdocs-glightbox
  2. git checkout 3.1.x and run the rest from the repo root.
  3. git fetch origin gh-pages:gh-pages
  4. Set canonical_version in mkdocs.yml to 3.1.x (SEO) and push it.
  5. mike alias 3.1.x latest -u --push
  6. mike set-default latest --push (only needed once; after that, moving latest is enough).
  7. Run the pages pipeline on the branch to publish, then check https://project.pages.drupalcode.org/ai/.