Skip to content

Latest commit

 

History

History
227 lines (184 loc) · 6 KB

CONTRIBUTING.adoc

File metadata and controls

227 lines (184 loc) · 6 KB
Raw

Contributors Guide

Improvements to Windup documentation are welcome.

In order to contribute, you will need a GitHub account and to have git installed on your machine. You can also log a {JiraWindupURL}[Jira issue] to track the changes.

Use the following steps to submit a change to the Windup documentation repository.

  1. Fork the windup-documentation GitHub repository.

    Click the Fork button in the top right corner of the page.

  2. Clone the forked repository locally.

    $ git clone [email protected]:YOUR_USERNAME/windup-documentation.git

  3. Add the upstream repository.

    git remote add -f upstream [email protected]:windup/windup-documentation.git

  4. Get the latest changes.

    $ git fetch upstream

  5. Check out a topic branch.

    $ git checkout -b BRANCH_NAME upstream/master

  6. Make the desired edits.

    The documentation is written in AsciiDoc. Review the AsciiDoc Guidelines and Tips section of this guide before making changes.

  7. Build the guides to verify your changes.

    1. Navigate to the appropriate guide’s directory and issue the following command. Note that you must have Asciidoctor installed.

      $ cd docs/cli-guide/
$ asciidoctor -t -dbook -a toc -o html/cli-guide.html master.adoc

    2. View the generated HTML file in a browser.

  8. Add each new or updated file to git.

    $ git add FILE_NAME.adoc

  9. Commit the changes locally.

    $ git commit -m "My commit message."

  10. Push the changes to your forked repository.

    $ git push origin HEAD

  11. Open a pull request to merge your changes to the master branch.

    1. Navigate to your forked repository in a browser: https://github.com/YOUR_USERNAME/windup-documentation.

    2. Open a new pull request. Be sure to review the diff before submitting.

    3. A member of the Windup documentation team will merge or provide feedback on your request.

Building the Guides

Navigate to the appropriate guide’s directory and issue the following command. Note that you must have Asciidoctor installed.

$ cd docs/cli-guide/
$ asciidoctor -t -dbook -a toc -o html/cli-guide.html master.adoc

View the generated HTML file in a browser.

Publishing the Guides

The Windup guides are published downstream on the Red Hat Customer Portal.

AsciiDoc Guidelines and Tips

AsciiDoc Editors

The following editors make editing and reviewing AsciiDoc files easy.

  • Atom with the asciidoc-preview and language-asciidoc packages.

  • AsciidocFX

  • Any basic editor, such as gedit, with the Chrome Asciidoctor.js plugin

AsciiDoc Syntax Basics

For a comprehensive reference of AsciiDoc syntax, see the AsciiDoc User Guide.

  • Headings

    = Heading Level 1
== Heading Level 2
=== Heading Level 3

  • Bold text

     *Bold text*

  • Italic text

    _Italic text_

  • Monospace text

    `Monospace text`

  • Bullets

    * Item one
* Item two

  • Numbered list

    . Step one
. Step two

  • Code block

    ----
System.out.println("Hello");
----

Creating a New AsciiDoc File

  • Name the file using only letters, numbers, and dashes, and with an extension of .adoc. For example, my-topic.adoc.

  • Add an anchor at the top of the file, using underscores. For example, [[my_anchor]].

  • Start each topic with a level one heading. For example, = My Heading.

  • Add this new topic to the master.adoc file using the include:: syntax.

    • Pass in a leveloffset=+N to adjust the heading levels in the included file to be the correct level.

Example master.adoc File
= My Guide Title

include::topics/my-topic.adoc[leveloffset=+1]
Example my-topic.adoc File
[[my_anchor]]
= My Heading

Text here.

== My Subsection

Text here.

Linking to Other Files

Use xref to link to a section within the same guide. You must define an explicit anchor in order to link.

Link to a Section in the Same Guide
For more information, see xref:section_anchor[This Section].
...

[[section_anchor]]
== This Section
...

Use link to reference an external URL.

Link to an External Link
Navigate to the link:https://github.com/windup/windup-documentation[Windup GitHub repository].

Using AsciiDoc Attributes

The Windup documentation defines several AsciiDoc attributes in the docs/templates/document-attributes.adoc file. This allows you to define the value one place and then used it repeatedly throughout the guides. An example usage of this is defining the Windup version.

Defining an Attribute

Define an attribute in the document-attributes.adoc file using the following syntax.

:ProductVersion: 5.0.0.Final

Using an Attribute

An attribute can then be referenced in an AsciiDoc file using the following syntax.

The Windup version is {ProductVersion}.

This will be resolved as "The Windup version is 5.0.0.Final".