Update User and Maintainer Docs

[krithika369]

Description

This PR updates the user docs and adds minimal maintainer docs for Merlin.

Note: Both the sets of docs are templatised using Jinja2 and the generated/* folder contains the final docs for Gitbook that are created by running the following locally:

make docs

Modifications

• docs/.gitignore - Ignore the mdformatter files used for formatting
• docs/Makefile - Add make targets for the docs
• docs/README.md - Include broad info about the different types of docs in the repo
• docs/SUMMARY.md - This file is not needed by the CaraML Gitbook docs and is removed.
• docs/developer/ - Minor corrections to the links in the dev docs
• docs/images/ - Add / update images
• docs/maintainer/ - Add maintainer docs.
  • docs/maintainer/values.json - Values file for the maintainer docs
  • A comment with the page-title is added to the .md files, to be able to publish the docs to Confluence, if needed.
  • The generated/ subfolder contains the final generated docs.
• docs/user/ - Add user docs.
  • docs/user/values.json - Values file for the maintainer docs
  • A comment with the page-title and parent-e-title is added to the .md files, to be able to publish the docs to Confluence, if needed.
  • The generated/ subfolder contains the final generated docs.
• examples/ - Renaming the notebooks referenced by the user docs to replace spaces with hyphens, to overcome limitation # 4 of the doc formatting tool: https://github.com/caraml-dev/mdformatter?tab=readme-ov-file#limitations

Tests

The following updates / tests are to be done after this PR is merged:

• Update the caraml-dev/docs repo, in particular, the SUMMARY.md file, to point to the generated/** doc files from Merlin repo.
• Verify that the CaraML docs are working as expected

Checklist

• Added PR label
• Added unit test, integration, and/or e2e tests
• Tested locally
• Updated documentation
• Update Swagger spec if the PR introduce API changes
• Regenerated Golang and Python client if the PR introduces API changes

Release Notes

Update User and Maintainer Docs

[ghost]

👇 Click on the image for a new way to code review

Legend

[leonlnj]

Thanks LGTM, dont have any concern.

Had some doubt about how the merging/override works but it is address in https://github.com/caraml-dev/mdformatter?tab=readme-ov-file#formatting

One more minor clarification, so the workflow for updating docs

1. Edit template/values
2. Make docs
3. Verify generated MD locally
4. Commit and push generated MD to branch
5. MR

[krithika369]

Thanks LGTM, dont have any concern.

Had some doubt about how the merging/override works but it is address in https://github.com/caraml-dev/mdformatter?tab=readme-ov-file#formatting

One more minor clarification, so the workflow for updating docs

1. Edit template/values
2. Make docs
3. Verify generated MD locally
4. Commit and push generated MD to branch
5. MR

Yes, that's correct.

[krithika369]

Thanks for the quick review, @leonlnj ! Will merge this PR shortly.