Windup Product Documentation

Overview

Windup project documentation is created collaboratively on the Windup project Wiki site located here: https://github.com/windup/windup/wiki. This windup-documentation repository takes documentation from that site, makes minor modifications, and publishes the pages in single HTML page book format. This repository will contain the source for the official documentation when the Windup ships.

Procedure to Update the Documentation With the Latest Windup Wiki

Check out a branch to work in.

Run the scripts/windupDocUpdate.sh script to copy the latest pages from the Wiki documentation and modify the files so they can be included in the Windup documentation guides.

• Copies the latest images and stylesheets.

• Copies the .asciidoc files to the docs/ directory and renames them with the .adoc extension.

• Replaces the link: macros to other pages with xref: macros since they are now included in the same book.

• Uses AsciiDoctor to generate HTML versions the guides in the html/ directory.

You must manually verify the following.

• Search the Guide to find pages that link to other pages and make sure the linked to pages are part of the book.

• Make sure every referenced page and section has a header matching the reference.

  [[section-header]]
  === Section Header
  ---
  
  Use Git to add files that have changed and issue the pull to merge them.
  
  == Procedure to Publish the Guides
  
  * The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream.
  In the following instructions, be sure to replace WINDUP_RELEASE with the actual release number.
  +

  git clone https://github.com/windup/windup.git git fetch upstream

* The first time, you must fork and clone the windup-documentation GitHub repository. After that, just fetch the latest upstream.
+

git clone https://github.com/windup/windup-documentation.git git fetch upstream

* Navigate to the local windup directory.
+

cd windup

* Checkout the gh-pages from the windup repository
+

git checkout -b gh-pages windup

* If the directory does not yet exist, create a docs/WINDUP-RELEASE-html/ directory.
+

mkdir -p docs/2.VERSION/html (if it doesn’t exist!)

* Copy any new images, stylesheets, and html files from windup-documentation:
+

cp ../windup-documentation/html/.html ../windup-documentation/.css ../windup-documentation/images/* docs/2.VERSION/html

* Add the updated files to GitHub.
+

git add docs

* Commit the changes.
+

git commit -m "Update message…​"

* Push the changes to GitHub.
+

git push upstream gh-pages

* Update the symlink so the "latest" release points to the newly published documentation.
+

unlink latest ln -s WINDUP_RELEASE latest git add latest git commit -m 'Replace symlink for latest to point to WINDUP_RELEASE' git push origin HEAD git push upstream gh-pages firefox http://windup.github.io/windup/docs/latest/html/WindupUserGuide.html

== Access the Guides

View the documentation at the following URLs.

[cols="2*"]
|===
| **Guide** | **URL**
| Windup User Guide | http://windup.github.io/windup/docs/latest/html/WindupUserGuide.html
| Windup Rules Development Guide | http://windup.github.io/windup/docs/latest/html/WindupRulesDevelopmentGuide.html
| Windup Core Development Guide | http://windup.github.io/windup/docs/latest/html/WindupCoreDevelopmentGuide.html
| Windup Migration Planning Guide | TBD
|===