First of all, you are welcome to email the Documentation Listserv (email@example.com) with problems you find in the documentation. However, we welcome you to participate in the process of improving things. Below are various ways you can contribute your time and skills.
Note: Changes to the official repository are processed into HTML daily at 1am. (see http://docs.evergreen-ils.org/)
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 the image below to see a screencast of this process (credit: Jane Sandberg)
This workflow is primarily for the few DIG members with permission to push to the master repository. If you do not have permission yet, you can start the request process by contacting the Git Admins group firstname.lastname@example.org. You can also push to another public repository, such as the Evergreen working repository or another host such as GitHub. Then email the DIG email list email@example.com with the location of your repository so they can pull your changes into master.
Use these procedures on Linux, Mac OS X, or GitBash on Windows.
First time only
git clone git://git.evergreen-ils.org/Evergreen.gitto create an initial copy of the repository on your machine. This will clone the whole Evergreen repository, which contains the docs directory where all the documentation lives.
cd Evergreen/docs- Moves to the new directory you just cloned.
If you aren't able to push to the documentation folder, try these troubleshooting steps:
firstname.lastname@example.org:Evergreen.git. Specifically, make sure that:
gitis followed by the
:, not a
git fetch --all
git checkout master
git pull- Pulls the most recent changes into your cloned version. This avoids merging issues and errors when "pushing" your changes to the remote repository.
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).
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.
asciidoc root_circulation.adoc- Converts AsciiDoc text files to HTML format. This will give you errors if the AsciiDoc format is incorrect. Once it succeeds, verify that the HTML appears as you expect. Finally, delete the output files (e.g.
rm *.html) to prevent them from being committed along with your AsciiDoc files.
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.
This allows you to "see" your changes as presented/integrated into the full site with Evergreen's look and feel
|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|
$ 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
When you are satisfied with your changes, commit the files.
git add- Tells git that you have added or edited files on your local machine and want to add them into the repository. The changes are not committed yet.
git status- Check to make sure that you are committing the correct files.
git commit -sOR
git commit -sm "Docs: [what you changed]"- Commits changes to the repository. You must provide a note on what you changed, beginning with the phrase "Docs: ". If you use the shorter form, a text editor will open (usually vim) where you will write your change note. (Using the -m switch is a time-saver if your note is short) To commit all changes, use
git commit ..
git log -3- Shows the 3 most recent commits. Check to make sure that your commit:
After you have committed to master
git checkout [BRANCH]- you will probably also want to add your change to the documentation for all relevant versions. For example, if you are documenting a feature that was added to version 3.2, you will want to add it to the 3.2 documentation. Release branches are in the form
rel_3_2, so for our example, you would type
git checkout rel_3_2.
git pull- if this branch has changed since the last time you ran this command.
git cherry-pick [NUMBER OF COMMIT]- if you didn't note the number of the commit, run
git checkout master; git log -3to find it. Then be sure to return to this branch with
git checkout [BRANCH].
If you are committing a change that somebody else made:
git commit -s --author="Firstname Lastname <email@example.com>"
If you try to push your change, but somebody has changed the Evergreen in the repo in the meantime, you will get this error:
error: failed to push some refs to 'https://git.evergreen-ils.org/REPOSITORY.git' To prevent you from losing history, non-fast-forward updates were rejected Merge the remote changes (e.g. 'git pull') before pushing again. See the 'Note about fast-forwards' section of 'git push --help' for details.
If this happens, you just have to run
git pull –rebase, which should bring in the latest changes and put your commit on top. After this, you can just repeat your
git push command.
These procedures are recommended if you are not comfortable with the command line.
First time only
git://git.evergreen-ils.org/Evergreen.git; leave "Target" blank to use the default path, or enter something else (it creates a new directory, so don't use one that exists already). Click Clone.
filename.adoc. Then you can proofread your document and look for anything strange.
Unstaged Changes(red). Click a file to see color-coded changes in the pane to the right.