Differences

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

--- evergreen-docs:how-to-contribute-documentation [2021/07/08 14:15] – aneiman
+++ evergreen-docs:how-to-contribute-documentation [2022/02/10 13:34] – external edit 127.0.0.1
@@ Line 5: / Line 5: @@
 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.
+**Note**: Changes to the official repository are processed into HTML daily at 1am. (see http://docs.evergreen-ils.org/)
-**Note**: Changes to the official repository are processed into HTML, PDF and ePub daily at 1pm and 11pm. (see http://docs.evergreen-ils.org/)
 ==== Beginner workflow ====
@@ Line 75: / Line 73: @@
 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.
 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 79: @@
   - ''%%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.