Page MenuHomePhabricator

Review supporting deployment pipeline documentation
Closed, ResolvedPublic

Description

Continuing from T352259, review the remaining technical documentation in the following sections:

Note that project documentation (e.g. rationale and discussions about the GitLab project) are not technical documentation and are therefore not in scope.

During the review:

  • mark documentation that no longer applies as deprecated/archived
  • update documentation that applies
  • indicate what documentation is missing. Either write new documentation where necessary, or create documentation tasks in Phabricator. Are there any features or tools in the pipeline that are not documented? Are there any drafts that need to be finalized?

Please reach out to @KBach if you need help, feedback, or want to collaborate on any of these. Feel free to create sub-tasks for parts of this work if necessary.

Details

TitleReferenceAuthorSource BranchDest Branch
Fix documentation site menurepos/releng/blubber!78kbachvitepress-menu-structuremain
Fix logo in vitepress, add syntax highlighting to code samplerepos/releng/blubber!77kbachvitepress-theme-fixesmain
Fix loading of assets in Blubber documentation on doc.wikimedia.orgrepos/releng/blubber!76kbachvitepress-fixmain
Add repos/releng/blubber to allowed_projectsrepos/releng/docpub!19dancymain-I718681cdf968f5165cd6375d4d30b12233a6b6b3main
Improve autogenerated documentation and introduce Vitepressrepos/releng/blubber!74kbachmain-I15a017adbfd7859ebe3442750f3ffba954239a26main
Customize query in GitLab

Event Timeline

KBach removed KBach as the assignee of this task.Nov 29 2023, 11:20 AM
KBach triaged this task as Low priority.
KBach created this task.
KBach changed the task status from Open to In Progress.Feb 22 2024, 10:37 AM
KBach claimed this task.

I have added this warning to Deployment pipeline and all of its sub-pages. Please feel free to boldly edit the template if you have any ideas for improvement.

Automatic generation of Blubber documentation from the JSON schema is a work in progress tracked in this merge request.

Review of GitLab documentation on mediawiki.org is done.

@brennen, the Gerrit to GitLab page has one TODO item. Are you able to have a look and fix/remove it? I'm not sure if it still applies.

kbach updated https://gitlab.wikimedia.org/repos/releng/blubber/-/merge_requests/74

Draft: Improve autogenerated documentation and introduce Vitepress

@KBach, out of curiosity more than anything, why choose Vitepress as the static site generator over the many, many other options?

@KBach, out of curiosity more than anything, why choose Vitepress as the static site generator over the many, many other options?

@bd808 Thanks for this question. When picking the site generator I considered around 5-6 options, but essentially ended up with these three: Vitepress, MkDocs, and Hugo. The first two we already use in other projects (Vitepress in Codex documentation, MkDocs in the Developer Portal). The third is written in Go, just like Blubber. My reasoning was that it would be easiest to find other people at the Foundation who are familiar with these generators and/or their underlying technology stacks, in case we need support.

After trying to set up all three I decided Vitepress is the most flexible, produces the tidiest structure and the nicest output with no extra dependencies and little configuration. I wanted something that's relatively easy to set up and maintain, especially since we are adding this to an existing repository, with its own structure and constraints.

That said, the documentation is quite small and it should be easy to replace Vitepress if anyone proposes something better.

Thank you for this description of the process and criteria @KBach. I might personally quibble that 59MiB of node modules is not exactly "no extra dependencies", but I understand your reasoning. :)

kbach opened https://gitlab.wikimedia.org/repos/releng/blubber/-/merge_requests/76

Fix loading of assets in Blubber documentation on doc.wikimedia.org

dancy merged https://gitlab.wikimedia.org/repos/releng/blubber/-/merge_requests/76

Fix loading of assets in Blubber documentation on doc.wikimedia.org

Change 1012376 had a related patch set uploaded (by KBach; author: KBach):

[integration/docroot@master] Add Blubber

https://gerrit.wikimedia.org/r/1012376

Change 1012376 merged by jenkins-bot:

[integration/docroot@master] Add Blubber

https://gerrit.wikimedia.org/r/1012376

Mentioned in SAL (#wikimedia-operations) [2024-03-18T16:22:01Z] <hashar@deploy2002> Started deploy [integration/docroot@b2c74b7]: doc: add Blubber - T352262

Mentioned in SAL (#wikimedia-operations) [2024-03-18T16:22:12Z] <hashar@deploy2002> Finished deploy [integration/docroot@b2c74b7]: doc: add Blubber - T352262 (duration: 00m 06s)

Blubber documentation is now available on https://doc.wikimedia.org/releng/blubber/. I have updated the links on Wikitech, marked the relevant pages as deprecated, and added Blubber to https://doc.wikimedia.org/#infrastructure.

Big thanks to @dduvall, @dancy, @jnuche, @hashar, and @thcipriani for their help in making this happen!

Marking GitLab documentation on Wikitech as reviewed. I reached out to @Jelto about minor changes to these pages. If needed, they will be handled in a separate task.

KBach updated the task description. (Show Details)