evergreen-docs:how-to-contribute-documentation
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
evergreen-docs:how-to-contribute-documentation [2018/05/01 23:13] – [Intermediate workflow] rjs7 | evergreen-docs:how-to-contribute-documentation [2022/04/04 15:08] – [Automatic build checker] aneiman | ||
---|---|---|---|
Line 1: | Line 1: | ||
===== How to Contribute Documentation to the Repository ===== | ===== How to Contribute Documentation to the Repository ===== | ||
- | First of all, you are welcome to email the Documentation Listserv ([[open-ils-documentation@list.georgialibraries.org]]) with problems you find in the documentation. | + | First of all, you are welcome to email the Documentation Listserv ([[evergreen-documentation@list.evergreen-ils.org]]) with problems you find in the documentation. |
- | We use [[http:// | + | We use [[http:// |
- | **Note**: Changes to the official repository are processed into HTML, PDF and ePub daily at 1pm and 11pm. (see http:// | + | **Note**: Changes to the official repository are processed into HTML daily at 1am. (see http:// |
- | + | ||
- | **Note**: **The documentation is now hosted in the main Evergreen git repository: | + | |
- | * [[http:// | + | |
==== Beginner workflow ==== | ==== Beginner workflow ==== | ||
- | * Send your documentation changes in any format to the Documentation Interest Group (DIG) email list: <open-ils-documentation@list.georgialibraries.org> | + | * Send your documentation changes in any format to the Documentation Interest Group (DIG) email list: <evergreen-documentation@list.evergreen-ils.org> |
* **Valuable contributions include:** | * **Valuable contributions include:** | ||
+ | * Telling us about anything that seems wrong | ||
* Corrections of typos | * Corrections of typos | ||
* Corrected step-by-step instructions | * Corrected step-by-step instructions | ||
Line 22: | Line 20: | ||
* URL of the documentation web page that needs to be updated | * URL of the documentation web page that needs to be updated | ||
* The part of the web page you are referring to (e.g. section heading, paragraph number, a nearby phrase, etc.) | * The part of the web page you are referring to (e.g. section heading, paragraph number, a nearby phrase, etc.) | ||
+ | |||
+ | ==== Beginner workflow with Launchpad ==== | ||
+ | * You may use Launchpad to report any errors or missing items you find in the documentation. | ||
+ | * Go to https:// | ||
+ | * Add the tag " | ||
+ | |||
+ | |||
==== Intermediate workflow ==== | ==== Intermediate workflow ==== | ||
Line 28: | Line 33: | ||
- Find the relevant file in the [[https:// | - Find the relevant file in the [[https:// | ||
* 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) | * 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 |
- | - If you are creating a new file, click the //plus// symbol that displays to the right of file path.Type in the file name. {{: | + | |
- Make your changes, using [[http:// | - Make your changes, using [[http:// | ||
- **Test that your AsciiDoc syntax is correct.** This is not required for simple typo corrections. | - **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 " | * PREVIEW as HTML: Any file on GitHub with the extension of " | ||
+ | * 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 | - Type a message describing your change | ||
- Click the " | - Click the " | ||
+ | - Click the green " | ||
- One of the developers will [[evergreen-docs: | - One of the developers will [[evergreen-docs: | ||
+ | |||
+ | A variation of this workflow is described [[https:// | ||
+ | |||
+ | ===== Automatic build checker ===== | ||
+ | |||
+ | As of 2021, Evergreen' | ||
+ | |||
+ | To access the test build file: | ||
+ | |||
+ | - Click on an existing pull request | ||
+ | - Select the tab labelled " | ||
+ | - In the upper left, select the dropdown labelled " | ||
+ | - 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 < | ||
+ | * You can search and navigate around the docs but note that the version dropdown doesn' | ||
+ | - 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) | ||
+ | |||
+ | {{: | ||
==== Advanced workflow ==== | ==== Advanced workflow ==== | ||
- | 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 < | + | 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 < |
=== Command line version === | === Command line version === | ||
Line 64: | Line 91: | ||
- Make changes to files, remove files, add new files | - Make changes to files, remove files, add new files | ||
- | After you've made your changes, make sure that your documentation is included in the appropriate | + | After you've made your changes, make sure that your documentation is included in the appropriate |
Then **test building the various output formats**. | Then **test building the various output formats**. | ||
Line 71: | Line 98: | ||
- '' | - '' | ||
- '' | - '' | ||
+ | |||
+ | === Build the Evergreen Documentation site locally === | ||
+ | |||
+ | **This allows you to " | ||
+ | |||
+ | * More details located in the Evergreen code repository: docs/ | ||
+ | * Be sure and have Node installed. see [[https:// | ||
+ | * Once Node is installed, follow the Antora prereqs. Summarized from [[https:// | ||
+ | * Now run generate_docs.pl | ||
+ | |||
+ | |||
+ | ^ | ||
+ | | base-url | URL where html output is expected to be available eg: http:// | ||
+ | | 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: | ||
+ | < | ||
+ | $ cd Evergreen/ | ||
+ | $ ./ | ||
+ | --base-url http:// | ||
+ | --tmp-space ../../tmp \ | ||
+ | --html-output / | ||
+ | --antora-ui-repo git:// | ||
+ | --antora-version 2.3 | ||
+ | </ | ||
+ | |||
+ | * 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. | When you are satisfied with your changes, commit the files. | ||
Line 91: | Line 150: | ||
- '' | - '' | ||
- Add a commit message that begins with " | - Add a commit message that begins with " | ||
+ | |||
+ | 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 ' | ||
+ | To prevent you from losing history, non-fast-forward updates were rejected | ||
+ | Merge the remote changes (e.g. 'git pull') before pushing again. | ||
+ | 'Note about fast-forwards' | ||
+ | </ | ||
+ | |||
+ | If this happens, you just have to run '' | ||
+ | |||
=== Graphical tool version === | === Graphical tool version === | ||
Line 109: | Line 180: | ||
- With your changed files highlighted, | - With your changed files highlighted, | ||
- To commit (a step that confirms your intention to make changes to the public repository), | - To commit (a step that confirms your intention to make changes to the public repository), | ||
- | - Finally, push your changes to the remote repository by clicking " | + | - Finally, push your changes to the remote repository by clicking " |
- If you get " | - If you get " | ||
- Once your changes are pushed to master, you should see them show up in the [[http:// | - Once your changes are pushed to master, you should see them show up in the [[http:// | ||
evergreen-docs/how-to-contribute-documentation.txt · Last modified: 2023/06/01 12:13 by gmcharlton