Add Readme

@abhiyanshu_rawat - this is a completely new module, do you know how it works? How would you write the README?

Hi @Marcus_Johansson, I understand your concern.
I just cloned this module locally and took a brief overview of it. Based on this overview and the features/details defined for this module on its detail page, I am compiling the necessary documentation and information and converting them into the README file.

• In merge request I think its too verbose. All URL pages don't need to be mentioned, maybe the starting point only and user will find the rest. Also try to avoid repeating the same what is already written in module page
• Readme core goal is to provide useful info how to actually use the module. I would like to see there documentation of APIs for developers (code examples).
• Also it does not mention dependencies and requirements, but says user can download the module and use it, but that means, user would run into serious issues. So requirements have to be listed, and to be recommended to install with composer or experiment the installation with project browser.

I think I can give example of my own module here 😁 because its covers these points https://git.drupalcode.org/project/aiprompt/-/blob/1.0.x/README.md?ref_t...
But also look to other examples.

@abhiyanshu_rawat as Marcus have said, if you haven't used the module, it can be a challenge to fulfill these points...

Completely agree with mindaugasd here.
I'll do a suggestion commit.
Let me know what you think.

Well done.

Part "Detailed Blog Post" is better to remove and link to the project page instead which contains latest constantly evolving education/marketing materials. While Readme should be likewise also constantly up-to-date about features, with the same commit as new APIs are implemented, so developers could immediately know them. So both types of content separated will be extensive and up-to-date.

Automator part is good, but does not really exist yet, so could be removed and be on project page.

Some more examples:
https://git.drupalcode.org/project/commerce/-/blob/8.x-2.x/README.md?ref...
https://git.drupalcode.org/project/key/-/blob/8.x-1.x/README.md?ref_type...
https://git.drupalcode.org/project/gin/-/blob/8.x-3.x/README.md?ref_type...

If module is very complex like 'commerce', then developer documentation is also moved out completely. And if simpler API module like 'key', then it has it. AI module should have it, because of being so fresh. And I would add a lot of different examples for developers of all APIs they can use.

I think each operation type and each provider needs to be documentation, I'm wondering if there is someway to make subpages in markdown from the Drupal documentation, so we don't have to rewrite the same documentation twice.

Yes Marcus you can do that (sub readme files).
I've added some sub pages, check it out.
Is it something like this you're looking for?

Looks really good!
AI would really like this (docs being within code repository).

We are not the first discussing this question, but quick search did not yield previous issues.

But found official docs about readme file:

• General: https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →
• Readme: https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →

There is also GitLab pages feature giving documentation nice look and navigation: https://docs.gitlab.com/ee/user/project/pages/

Some examples:

• https://project.pages.drupalcode.org/gitlab_templates/
• https://project.pages.drupalcode.org/api_client/ <---
• https://project.pages.drupalcode.org/core_logs/
• https://project.pages.drupalcode.org/decoupled_lb

Nice but also - All of them- look different. (which is a feature i guess).
Markdown files are really nice too and uniform across drupal.org 😅
I'm more of the opnion "done is better than perfect" so whatever works and costs minimal effort to maintain.

@seogow suggested https://www.mkdocs.org/ and I have done some minor research on it and compared it to Hugo an Jekyll that I worked with before, and it seems more fit to the task.

It can handle styling, client based search and can in theory build from multiple repos if needed. There are also example implementations in https://gitlab.com/pages/mkdocs

Of course this will then lead to 100s of MD files inside the AI module and its submodule, but I think people can live with 1-2 MB of md files - any proper production setup should use build jobs to remove them (and test files) before being pushed to production anyway.

Of course this will then lead to 100s of MD files inside the AI module and its submodule, but I think people can live with 1-2 MB of md files - any proper production setup should use build jobs to remove them (and test files) before being pushed to production anyway.

Modules usually don't have 100s of MD files. This is new thing. What does it mean of having it now? And those files will be there, not removed. Future Drupal is to install and use easily without production setup.

I guess it mean nothing. Modules don't have it, but js libraries do have it, which is the same.

The other option is that we create a repo for the documentation pages, but the same would be true for testing code where there are modules with a larger code stack in the tests directory then the actual module code.

The option is that both these are other repos that are fetched as composer dev dependencies for testing and building documentation, I'm not sure how much harder it makes to work with it if we always have to do 3 repos.

Anyone that doesn't want to do production builds should ideally use something like Pantheon, platform.sh or Acquia where they take care of obfuscating this for you. The MD files are a minimal security concern, where you at best can figure out older unsecured versions, compared to showing web.config or some other files that ships with core.

@wouters_f

done is better than perfect

Having documentation looking as https://ecaguide.org/ or https://docs.drupalcommerce.org/v2/developer-guide/ is very attractive, when documentation size grows.

Readme files alone would become difficult to navigate, but with https://www.mkdocs.org/ md will still be available.

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

When linking between pages in the documentation you can simply use the regular Markdown linking syntax, including the relative path to the Markdown document you wish to link to.

Interpolator have very good documentation https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib... → which can be ported to md files git version controlled. It will take clicking "Edit" and merge on drupalcode.org to edit something for someone in docs.

have to do 3 repos

I would prefer one.

The MD files are a minimal security concern, where you at best can figure out older unsecured versions

If that is all, then it is fine.

Hi there!

After pouring through the various links and getting up to speed with the Slack chat and the 3 videos released for alpha 6, I'm looking to contribute time to this module and thought I'd start with docs. I was surprised there wasn't already a README and found this issue. Perhaps I can help?

---
Proposed action plan:

1. Create a Minimal Viable README
- Focus on essential information only
- Include:
- Brief module description
- Basic installation instructions
- Simple usage example
- Link to full documentation (to be developed)

2. Set Up Documentation Infrastructure
- Create a build-docs script that reads the docs from [Drupal documentation]( https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib... → )
- creates the sub-files in the docs folder in the main repository
- can utilize the REST API to get doc body but would need to list the node IDs because relationship information doesn't exist >:|
- ex: AI → , How to set up a provider → , AI: How to use it or integrate it in contrib modules →

3. Develop Documentation Incrementally
- Start with core module functionality
- Add sections for each major feature/API
- Include code examples for developers
- Run the build-docs script anytime docs change
---

This would address @marcus_johansson's comment above:

I'm wondering if there is someway to make subpages in markdown from the Drupal documentation, so we don't have to rewrite the same documentation twice.

See https://git.drupalcode.org/issue/ai-3455852/-/compare/1.0.x...3455852-bu... where I have a branch with a working POC.

I'd say we get started. The readme living in this branch will probably be deprecated by now .
Readme files in the repo would have been better already.
In other words I love the KISS approach The simpler the better, if only it works.

Sorry, that I have kept pushing this and thanks for the work done here @sirktree.

One thing I think is important, is that the documentation actually resides and is written in the code base, not on drupal.org. I did try to keep the documentation up to date with the AI Interpolator as you can see here ( https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib... → ) with over 100 pages and its just a horrible experience. It takes 10-15 seconds when you click that you want to create a page, then you have to write HTML in a quasi WYSIWYG editor. I spent most of my time documenting then building stuff.

I would take it the other step and see if we can write something - if needed that writes MD files to the documentation. But I think having a gitlab pages with all the documentation and linking there is better. So MKDocs building static pages.

But to start with, independent on this, just having README files is a very good start in general!

Found this - its actually minimal work: https://project.pages.drupalcode.org/gitlab_templates/jobs/pages/

I will setup a base installation of it, just so we have something.

So I tried to implement this a little bit, and there is one issue - the docs folder can't be in root and it can't go outside of the docs folder for its build. This means that the documentation structure would be like this

mkdocs.yml
docs/index.md
docs/developer_documentation.md
docs/modules/ai_ckeditor/index.med

And then we would have to have README.md in each module root with some general documentation or linking to this.

The option is that we do one of the following in the build script:
1. Symlink all the submodules into docs directory on build.
2. Copy all the submodules markdown files into the docs directory on build.
3. Use https://github.com/backstage/mkdocs-monorepo-plugin

Any thoughts?

I would go with "2. Copy all the submodules markdown files into the docs directory on build."

Thanks! Here's a Draft MR: https://git.drupalcode.org/project/ai/-/merge_requests/78

update to .gitlab-ci.yml

- add in the pages section for building mkdocs (untested as i've never used this feature before)

adding build-docs.py

- a basic script that will
- copy the main readme into docs as index.md
- search through submodule dirs for README files
- copy those into the appropriate destination in docs

adding mkdocs.yml

- defines the basic structure of the documentation site for us with mkdocs
- note this will need to be manually updated for any new README created in submodules

Adding basic README and beginning of structure for docs

- Basic README and corresponding index in /docs
- copied documentation from docs.drupal.org in md format inot /docs
- copied the README's found in submodules into /docs with mirrored structure as index.md files

Thanks! Sorry, about the merge conflicts, I'm currently fixing up so we have perfect code, so a lot of changes including the gitlab file. I'll make sure to fix the MR and have a look!

Do we have enough to close this issue now? If not, what parts are missing?

1. What the module is.

AI (artificial intelligence) integration for Drupal - a unified framework for integrating various AI models and services into your Drupal site.

2. How to install it.

## Getting Started

1. Enable the AI module.
2. Choose and enable an AI provider submodule (e.g., OpenAI, Huggingface, Mistral).
3. Configure your API key in the Key module.
4. Configure the AI module at `/admin/config/ai/settings`.
5. Enable desired submodules for specific functionality.

3. Example setup (install module, openai provider and goto explorer and test a chat message).
Nothing specifically about this ...

4. External links to provider lists.
Some good info in https://project.pages.drupalcode.org/ai/modules/providers/provider_ollama/

5. Internal links to submodules README.
Submodules that have readmes are listed under modules: https://project.pages.drupalcode.org/ai/

We have a lot to document, but I think this is a great start and can be closed and then we can create new issues for documenting specific parts of the submodules.

marcus_johansson → closed merge request !4

Automatically closed - issue fixed for 2 weeks with no activity.