The Image Link Formatter module currently provides documentation primarily through its README file. To improve documentation accessibility, discoverability, and maintainability, we should implement a GitLab Pages documentation site using the standardized MkDocs approach supported by Drupal's GitLab templates.
A GitLab Pages site will provide:
Implement a GitLab Pages documentation site for the Image Link Formatter module following the standard Drupal GitLab templates approach documented at: https://project.pages.drupalcode.org/gitlab_templates/jobs/pages/
mkdocs.yml in project root)
logo.png file/docs folder)
docs/index.md as the homepageDeploy > Pages > Domains & settingspages job runs on commits to the default branchimage_link_formatter/
├── mkdocs.yml
├── logo.png (existing)
└── docs/
├── index.md (homepage)
├── installation.md
├── configuration.md
├── usage.md
├── troubleshooting.md
└── developer/
└── architecture.md (optional)
Show commandsStart within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
changes
Comments
Comment #4
dydave commentedQuick follow-up on this issue:
This ticket was initially prompted by the need of finding an appropriate place in the module to store AI "spec-driven" prompts and PLAN/SPECS.md types of files.
I thought documentation would be a "safer" space to work with AI and give more trust to its generated content.
Since I saw there was a new documentation job supported in the gitlab CI builds for documentation, I thought it would be a great opportunity to try producing everything with AI.
So I started by adding the mkdocs.yml config file with the specs files in the
docs/specsfolder and then thought of expanding with different sections: User guide, developer, etc...The README.md file served as a great starting point.
I actually spent most of the time refining the documentation:
Each time I would preview the md files locally and think of new things to add or modify.
It was a very iterative process which I tried to keep documented in the file: GITLAB_PAGES_SPEC.md.
At a very small scale, I tried to apply a "spec-driven" approach and refine as much as possible a specifications document to specify certain tasks or rules for the AI agent.
A lot of issues were thankfully caught by the quality gates: breaking build pipelines on Gitlab CI, which is a really great thing.👍
Among some of the problems encountered:
I deployed the documentation several times by triggering builds manually on the issue fork repos which allowed me to fully test the rendered output of all the pages.
Since all the jobs and tests were still passing all 🟢, I went ahead and merged the changes above at #3.
The documentation site is now live at: 🥳
https://project.pages.drupalcode.org/image_link_formatter/
The last build with all jobs came back all green 🟢:
https://git.drupalcode.org/project/image_link_formatter/-/pipelines/899870
I already updated the project page to add a section to point to the new documentation:
https://www.drupal.org/project/image_link_formatter#documentation
I'm sure we will think of other things to add or modify in the documentation, but this is already a great initial base for such a small module on which we should be able to keep building in the future. 👌
Since I don't see any more actions to be carried in this issue, we could most likely consider all the work initially described and expected should have been completed at this point.
Therefore, marking issue as Fixed for now.
Feel free to let us know if you have any questions or concerns on any aspects of the documentation or the module in general, we would surely be glad to hear your feedback.
Thanks in advance!