Differences

This shows you the differences between two versions of the page.

--- evergreen-docs:how-to-contribute-documentation [2021/07/08 18:03] – Integrating the Antora build procedure bmagic
+++ evergreen-docs:how-to-contribute-documentation [2022/04/04 15:22] – [Intermediate workflow] aneiman
@@ Line 33: / Line 33: @@
   - Find the relevant file in the [[https://github.com/evergreen-library-system/Evergreen/tree/master/docs|GitHub repository]]
     * Look around until you find the content (note: the directories are mostly logically similar to the online docs table of contents sections, but may require some searching around)
-  - Click the pencil ("Edit this file") icon to edit the file in your browser
+  - Click the pencil ("Edit this file") icon to edit the file in your browser **OR** If you are creating a new file, click the Add File button. Type in the file name. Make sure you are in the correct directory.
-  - If you are creating a new file, click the //plus// symbol that displays to the right of file path.Type in the file name. {{:evergreen-docs:github-create.png}}
   - Make your changes, using [[http://powerman.name/doc/asciidoc|correct AsciiDoc format]].
   - **Test that your AsciiDoc syntax is correct.** This is not required for simple typo corrections.
        * PREVIEW as HTML: Any file on GitHub with the extension of ".adoc" should auto-display the HTML version of the file when previewed or saved. Then you can proofread your document and look for anything strange.
+       * Note that there is now an automatic checker in github that will build a test copy of your docs. Instructions on that are below.
   - Type a message describing your change
   - Click the "Propose file change" button
@@ Line 44: / Line 44: @@
 A variation of this workflow is described [[https://youtu.be/XiVjO_S0Y-s|in this YouTube video]].
+An alternative of the above workflow using GitHub Desktop is [[https://docs.evergreen-ils.org/eg/docs/latest/shared/how_to_contribute_docs.html|here]]
+=== Automatic build checker ===
+As of 2021, Evergreen's github repository contains a tool that will build a full Antora-ized copy of the docs whenever someone opens a github pulllrequest that includes documentation changes. You can download this copy and view it in your browser to make sure things like image files and internal links are operating correctly.
+To access the test build file:
+  - Click on an existing pull request
+  - Select the tab labelled "Checks"
+  - In the upper left, select the dropdown labelled "Artifacts"
+  - Click the file built-docs to download a zipped copy of the docs build
+  - Unzip the file and double-click on index.html in the extracted folder. This will open a preview version of the Antora docs pages in your browser.
+    * On Windows, the address bar will read <code>file:///C:/Users/<username>/Downloads/built-docs/docs/latest/shared/about_this_documentation.html</code>
+    * You can search and navigate around the docs but note that the version dropdown doesn't currently work.
+  - Search for the file(s) you've added or changed, and click around them to make sure everything looks and works as expected.
+Click on the image below to see a screencast of this process (credit: Jane Sandberg)
+{{:evergreen-docs:built-docs_1_.gif?direct&200|}}