It's worth a lot, Jane! I really like how you've made the automated builds in Github a way for doc writers to see a preview of their proposed changes. I think I can make GitLab support that use case as well--GitLab CI seems quite comparable to Github Actions (although GitLab argues that GitLab CI offers many more advantages <https://about.gitlab.com/devops-tools/github-vs-gitlab/ci-missing-github-capabilities/>, naturally)...
On Thu, 30 Dec 2021 at 14:24, Jane Sandberg <[email protected]> wrote: > For what it is worth, I have a pull request to do something similar for > Github, using the existing generate_docs script: > https://bugs.launchpad.net/evergreen/+bug/1903476 > > Whether on Github or Gitlab, I am very supportive of using these CI tools > to simplify our workflows. > > On Thu, Dec 30, 2021 at 10:06 AM Floyd, Angelia Lynn via > Evergreen-documentation <[email protected]> > wrote: > >> As I like this concept and the lowering of the bar for edits, my main >> concern is that we currently have people adding docs two different ways. >> >> 1. Straight to the working Git Repo >> 2. Via GitHub >> >> >> >> Will the use of GitLab incorporate both of these methods for adding docs? >> >> >> >> I think definitely a further discussion on this process and how to best >> use it at the next DIG meeting is a must. >> >> >> >> ----------------------------- >> Lynn Floyd >> MIS Supervisor >> >> Indiana State Library >> 317-232-3290 >> [email protected] >> >> >> >> *From:* Evergreen-general < >> [email protected]> *On Behalf Of *Dan >> Scott via Evergreen-general >> *Sent:* Thursday, December 30, 2021 11:45 AM >> *To:* [email protected] >> *Subject:* Re: [Evergreen-general] Automating Antora documentation >> builds on GitLab >> >> >> >> **** This is an EXTERNAL email. Exercise caution. DO NOT open attachments >> or click links from unknown senders or unexpected email. **** >> ------------------------------ >> >> I took things a little further today. >> >> >> >> The GitLab docs build now includes the Evergreen CSS, header, and footer. >> The UI bundle is currently sourced from a pinned job from an automated >> build of the "evergreen" branch of the Antora default UI ( >> https://gitlab.com/denials/antora-ui-default/-/tree/evergreen [1]) I set >> up. >> >> >> >> The UI bundle is currently in my GitLab namespace for testing purposes >> but it would be easy to move the repository to GitLab's >> evergreen-library-system group. I suggest mirroring the >> Antora/antora-ui-default main branch (GitLab makes mirroring trivial) and >> keeping our customizations in an "evergreen" branch to avoid merge hassles, >> etc. >> >> >> >> If we were willing to rely on GitLab's automated builds, we could remove >> docs/generate_docs.pl >> <https://protect2.fireeye.com/v1/url?k=b33ef7c2-eca5cedd-b33abec2-8630ffab37ab-13f03a9685753a65&q=1&e=7b0675b3-8f20-4e04-83dc-82cedabdf6e5&u=http%3A%2F%2Fgenerate_docs.pl%2F> >> and replace docs/site.yml. We wouldn't need to maintain a special server to >> build and serve the Evergreen documentation. We could even have GitLab >> serve up the docs.evergreen-ils.org >> <https://protect2.fireeye.com/v1/url?k=5ae76b66-057c5279-5ae32266-8630ffab37ab-2e16b86f003fd1ac&q=1&e=7b0675b3-8f20-4e04-83dc-82cedabdf6e5&u=http%3A%2F%2Fdocs.evergreen-ils.org%2F> >> domain, given that Evergreen 3.6 marks the first Antora-based documentation >> and is currently in "only security fix mode". Or we could continue to serve >> up docs.evergreen-ils.org >> <https://protect2.fireeye.com/v1/url?k=4b8ac5b6-1411fca9-4b8e8cb6-8630ffab37ab-d8bb1bad123ab804&q=1&e=7b0675b3-8f20-4e04-83dc-82cedabdf6e5&u=http%3A%2F%2Fdocs.evergreen-ils.org%2F> >> on our own server along with the legacy docs by automating the downloading >> & unzipping of the artifacts bundle (all the HTML/CSS/JS/media) GitLab >> creates with each build. >> >> >> >> Depending on how far we wanted to go with GitLab integration, we could >> also unhide the "Edit this page" link on every page of the Evergreen >> documentation that leads to the corresponding file in the GitLab repository >> and the web IDE. That might be a lower bar for basic documentation >> contributions (e.g. fixing typos or adding a clarification) than our >> current footer's suggestion to email the DIG list (which, based on the list >> archives, doesn't seem to be attracting many contributions). Edits made via >> the Web IDE create a merge request (& potentially a branch) per >> https://docs.gitlab.com/ee/user/project/web_ide/#commit-changes so >> contributors wouldn't have to learn git mechanics to edit existing files. >> >> >> >> On Wed, 29 Dec 2021 at 14:30, Dan Scott <[email protected]> wrote: >> >> I was exploring GitLab's CI/CD (continuous integration / delivery) >> functionality last night/this morning and decided to try building our >> Antora-based documentation this way with the output hosted on GitLab Pages. >> >> >> >> It works quite nicely. I've posted a rough implementation branch at >> https://gitlab.com/evergreen-library-system/evergreen-library-system/-/commits/gitlab-antora-build >> >> >> >> As you can see, it's just a couple of YAML files; .gitlab-cy.yml defines >> the "pages" step, and .gitlab-antora.yml defines a custom Antora playbook >> for the Docker environment. The CI/CD piece means that a new build would be >> triggered by every commit. >> >> >> >> The output is visible at >> https://evergreen-library-system.gitlab.io/evergreen-library-system/docs/latest/index.html >> <https://protect2.fireeye.com/v1/url?k=caca5588-95516c97-cace1c88-8630ffab37ab-97c482cf18007337&q=1&e=7b0675b3-8f20-4e04-83dc-82cedabdf6e5&u=https%3A%2F%2Fevergreen-library-system.gitlab.io%2Fevergreen-library-system%2Fdocs%2Flatest%2Findex.html> >> >> >> >> It's nice to see the current list of build errors, such as missing >> references or media files, at a glance: >> https://gitlab.com/evergreen-library-system/evergreen-library-system/-/jobs/1927489146 >> >> >> >> If we decided to merge this, we would want to modify the configuration so >> that it only watches a given branch (our main branch, most likely), rather >> than triggering a new build for every commit on every branch. But most of >> the doc build could also be reused as an integration test to be run against >> every branch / merge request. If a test fails, then the merge request gets >> flagged, the errors get reported as a comment right on the branch/merge >> request (instead of having to dig into the job details), and the branch >> could be blocked from merging until the problem is resolved. >> >> >> >> I'm using the Node.js npx command to avoid having to globally install the >> npm modules. npx is a nice way to avoid conflicts between requirements for >> different module versions at the global level and to avoid having to run >> commands as root. When you prefix a command with "npx", such as "npx >> antora", it searches for the command within the local project's >> node_modules path instead of globally. Could be useful elsewhere in >> Evergreen. >> >> >> >> Notes: >> >> * I updated the build process to use the just-released Antora 3 and the >> corresponding Antora lunr-extension. >> >> * I have not applied the Evergreen customizations of CSS, the header >> menu, or the contact DIG message in the footer. Antora 3 has moved to >> "extensions" which are lighter weight than our current approach of cloning >> and tweaking the Antora default UI repository. >> >> * In addition to the basic "does Antora build the docs without errors" >> integration test, we could add a style checker like Vale ( >> https://gitlab.com/jdkato/vale) as another test for the documentation. >> Vale can flag spelling errors (with a custom dictionary of course) and >> grammatical issues like passive voice, etc. >> >> _______________________________________________ >> Evergreen-documentation mailing list >> [email protected] >> >> http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-documentation >> > > > -- > Jane Sandberg > Electronic Resources Librarian > Library Department Chair > Linn-Benton Community College > [email protected] / 541-917-4655 > Pronouns: she/her/hers > > Library instagram: @lbcc_library <https://www.instagram.com/lbcc_library/> > > >
_______________________________________________ Evergreen-general mailing list [email protected] http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-general
