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 revisionLast revisionBoth sides next revision | ||
evergreen-docs:how-to-contribute-documentation [2021/07/08 14:15] – aneiman | evergreen-docs:how-to-contribute-documentation [2022/04/04 15:22] – [Intermediate workflow] aneiman | ||
---|---|---|---|
Line 5: | Line 5: | ||
We use [[http:// | We use [[http:// | ||
- | 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:// |
- | + | ||
- | **Note**: Changes to the official repository are processed into HTML, PDF and ePub daily at 1pm and 11pm. (see http:// | + | |
==== Beginner workflow ==== | ==== Beginner workflow ==== | ||
Line 35: | 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 " | ||
Line 46: | Line 44: | ||
A variation of this workflow is described [[https:// | A variation of this workflow is described [[https:// | ||
+ | An alternative of the above workflow using GitHub Desktop is [[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) | ||
+ | |||
+ | {{: | ||
Line 75: | Line 93: | ||
After you've made your changes, make sure that your documentation is included in the appropriate module(s). | After you've made your changes, make sure that your documentation is included in the appropriate module(s). | ||
- | |||
- | FIXME the test build instructions need to be updated for Antora. | ||
Then **test building the various output formats**. | Then **test building the various output formats**. | ||
Line 83: | Line 99: | ||
- '' | - '' | ||
- '' | - '' | ||
+ | |||
+ | === 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. |
evergreen-docs/how-to-contribute-documentation.txt · Last modified: 2023/06/01 12:13 by gmcharlton