<div dir="ltr"><div>Hi Lynn:</div><div><br></div><div>Adding GitLab as a third potential way to contribute docs is certainly a valid concern, and worthy of discussion! I'll try to make it to the next DIG meeting.<br></div><div><br></div><div>Best,</div><div>Dan<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, 30 Dec 2021 at 13:06, Floyd, Angelia Lynn <<a href="mailto:LFloyd1@library.in.gov">LFloyd1@library.in.gov</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div style="overflow-wrap: break-word;" lang="EN-US">
<div class="gmail-m_-7686670244339335980WordSection1">
<p class="MsoNormal">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.<u></u><u></u></p>
<ol style="margin-top:0in" type="1" start="1">
<li class="gmail-m_-7686670244339335980MsoListParagraph" style="margin-left:0in">Straight to the working Git Repo<u></u><u></u></li><li class="gmail-m_-7686670244339335980MsoListParagraph" style="margin-left:0in">Via GitHub<u></u><u></u></li></ol>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">Will the use of GitLab incorporate both of these methods for adding docs?
<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">I think definitely a further discussion on this process and how to best use it at the next DIG meeting is a must.
<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<div>
<p class="MsoNormal"><span style="font-size:12pt;font-family:"Arial",sans-serif;color:black;background:white none repeat scroll 0% 0%">-----------------------------</span><br>
Lynn Floyd<br>
MIS Supervisor<u></u><u></u></p>
<p class="MsoNormal">Indiana State Library<br>
317-232-3290<br>
<a href="mailto:lfloyd1@library.in.gov" target="_blank"><span style="color:rgb(5,99,193)">lfloyd1@library.in.gov</span></a><span style="font-size:10pt;font-family:"Arial",sans-serif"><u></u><u></u></span></p>
</div>
<p class="MsoNormal"><u></u> <u></u></p>
<div>
<div style="border-color:rgb(225,225,225) currentcolor currentcolor;border-style:solid none none;border-width:1pt medium medium;padding:3pt 0in 0in">
<p class="MsoNormal"><b>From:</b> Evergreen-general <<a href="mailto:evergreen-general-bounces@list.evergreen-ils.org" target="_blank">evergreen-general-bounces@list.evergreen-ils.org</a>>
<b>On Behalf Of </b>Dan Scott via Evergreen-general<br>
<b>Sent:</b> Thursday, December 30, 2021 11:45 AM<br>
<b>To:</b> <a href="mailto:evergreen-general@list.evergreen-ils.org" target="_blank">evergreen-general@list.evergreen-ils.org</a><br>
<b>Subject:</b> Re: [Evergreen-general] Automating Antora documentation builds on GitLab<u></u><u></u></p>
</div>
</div>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><span style="font-size:12pt;font-family:"Arial",sans-serif;color:red">**** This is an EXTERNAL email. Exercise caution. DO NOT open attachments or click links from unknown senders or unexpected email. ****</span>
<u></u><u></u></p>
<div class="MsoNormal" style="text-align:center" align="center">
<hr width="100%" size="2" align="center">
</div>
<div>
<div>
<div>
<p class="MsoNormal">I took things a little further today.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">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 (<a href="https://gitlab.com/denials/antora-ui-default/-/tree/evergreen" target="_blank">https://gitlab.com/denials/antora-ui-default/-/tree/evergreen</a>
[1]) I set up.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">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.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">If we were willing to rely on GitLab's automated builds, we could remove docs/<a href="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" target="_blank">generate_docs.pl</a>
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
<a href="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" target="_blank">
docs.evergreen-ils.org</a> 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
<a href="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" target="_blank">
docs.evergreen-ils.org</a> 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.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">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 <a href="https://docs.gitlab.com/ee/user/project/web_ide/#commit-changes" target="_blank">
https://docs.gitlab.com/ee/user/project/web_ide/#commit-changes</a> so contributors wouldn't have to learn git mechanics to edit existing files.<u></u><u></u></p>
</div>
</div>
<p class="MsoNormal"><u></u> <u></u></p>
<div>
<div>
<p class="MsoNormal">On Wed, 29 Dec 2021 at 14:30, Dan Scott <<a href="mailto:dan@coffeecode.net" target="_blank">dan@coffeecode.net</a>> wrote:<u></u><u></u></p>
</div>
<blockquote style="border-color:currentcolor currentcolor currentcolor rgb(204,204,204);border-style:none none none solid;border-width:medium medium medium 1pt;padding:0in 0in 0in 6pt;margin-left:4.8pt;margin-right:0in">
<div>
<div>
<div>
<p class="MsoNormal">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.
<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">It works quite nicely. I've posted a rough implementation branch at
<a href="https://gitlab.com/evergreen-library-system/evergreen-library-system/-/commits/gitlab-antora-build" target="_blank">
https://gitlab.com/evergreen-library-system/evergreen-library-system/-/commits/gitlab-antora-build</a>
<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">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.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">The output is visible at <a href="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" target="_blank">
https://evergreen-library-system.gitlab.io/evergreen-library-system/docs/latest/index.html</a><u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">It's nice to see the current list of build errors, such as missing references or media files, at a glance:
<a href="https://gitlab.com/evergreen-library-system/evergreen-library-system/-/jobs/1927489146" target="_blank">
https://gitlab.com/evergreen-library-system/evergreen-library-system/-/jobs/1927489146</a><u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<div>
<p class="MsoNormal">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.<u></u><u></u></p>
</div>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">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.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">Notes:<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal">* I updated the build process to use the just-released Antora 3 and the corresponding Antora lunr-extension.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal">* 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.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal">* In addition to the basic "does Antora build the docs without errors" integration test, we could add a style checker like Vale (<a href="https://gitlab.com/jdkato/vale" target="_blank">https://gitlab.com/jdkato/vale</a>) as another test
for the documentation. Vale can flag spelling errors (with a custom dictionary of course) and grammatical issues like passive voice, etc.<u></u><u></u></p>
</div>
</div>
</div>
</blockquote>
</div>
</div>
</div>
</div>
</blockquote></div>