Differences

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

--- evergreen-docs:how-to-contribute-documentation [2021/07/08 17:05] – Addressed the FIXME's bmagic
+++ evergreen-docs:how-to-contribute-documentation [2022/04/04 15:22] – [Intermediate workflow] aneiman
@@ Line 4: / Line 4: @@
 We use [[http://git-scm.com/|Git]] for version control on documentation. The official repository is housed on the Evergreen git server [[http://git.evergreen-ils.org/?p=Evergreen.git;a=tree;f=docs;hb=HEAD|git.evergreen-ils.org]].
-FIXME is the below statement still accurate? I know the PDF / HTML part is not, but curious about the rebuild timing. - [Updated - bmagic, fixme could be removed]
 **Note**: Changes to the official repository are processed into HTML daily at 1am. (see http://docs.evergreen-ils.org/)
@@ Line 35: / 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 46: / 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|}}
@@ Line 75: / Line 93: @@
 After you've made your changes, make sure that your documentation is included in the appropriate module(s).  To do this, make sure that there is a cross reference statement like ''%%**%% xref:acquisitions:acquisitions_search.adoc[Acquisitions Search]'' in the appropriate ''nav.adoc'' file (e.g. ''docs/modules/acquisitions/nav.adoc'' for the Acquisitions module).
-FIXME the test build instructions need to be updated for Antora. [bmagic - These instructions are still valid for converting single files for general validity. Do we want to append a paraphrased docs/README.adoc here or elsewhere on this page?]
 Then **test building the various output formats**.  The following examples use the Circulation manual, but you will want the filename ''root_circulation.adoc'' to match the manual you are trying to test.
@@ Line 83: / Line 99: @@
   - ''%%a2x --fop root_circulation.adoc%%'' - Converts AsciiDoc text files to PDF format. Verify that the PDF appears as you expect.  Finally, delete the output files (e.g. ''rm *.pdf'') to prevent them from being committed along with your AsciiDoc files.
   - ''%%a2x --format=epub root_circulation.adoc%%'' - Converts AsciiDoc text files to ePub format. Once it succeeds, delete the output files (e.g. ''rm *.epub'') to prevent them from being committed along with your AsciiDoc files.
+=== Build the Evergreen Documentation site locally ===
+**This allows you to "see" your changes as presented/integrated into the full site with Evergreen's look and feel**
+  * More details located in the Evergreen code repository: docs/README.adoc
+  * Be sure and have Node installed. see [[https://github.com/nvm-sh/nvm#installation-and-update|Installing Node]]
+  * Once Node is installed, follow the Antora prereqs. Summarized from [[https://docs.antora.org/antora/2.3/install/linux-requirements/|Antora pre-reqs]]
+  * Now run generate_docs.pl
+^           generate_docs.pl options          ^^
+| base-url | URL where html output is expected to be available eg: http://localhost |
+| tmp-space | Writable path for staging the antora UI repo and build files, defaults to ./build |
+| html-output | Path for the generated HTML files, defaults to ./output |
+| antora-ui-repo | Antora-UI repository for the built UI |
+| antora-version | Version of antora to use for build, defaults to 2.3 |
+  * Example:
+<code>
+$ cd Evergreen/docs
+$ ./generate_docs.pl  \
+--base-url http://localhost/prod \
+--tmp-space ../../tmp \
+--html-output /var/www/html/prod \
+--antora-ui-repo git://git.evergreen-ils.org/eg-antora.git \
+--antora-version 2.3
+</code>
+  * To view the site perfectly, you will need to have a web server running on your computer.
 When you are satisfied with your changes, commit the files.