About Project Hop documentation
The hop documentation project consists of multiple types of documentation. Each with their own purpose.
Hop User manual
The user manual contains general guidelines and info for starting hop users and reference material about actions and transforms for the more advanced users. It will contain Frequently Asked Questions and step by step samples
A part of the user manual is imported from the main HOP repository, the database,action and transform documentation is maintained together with the code.
Hop Tech manual
This reference guide will contain reference architectures and more advanced configuration and set-ups using HOP
Hop Development manual
The Development manual contains information on how to create plugins and how the code of HOP works.
Structure
When opening one of the three documentation folders you will notice there are two modules one is called ROOT the other is asciidoctor. The ROOT module contains all the content, the asciidoctor is a placeholder to generate a PDF book based on the ROOT module.
The asciidoctor module is currently not being used, it is a future project
Under the ROOT module you will find following folders:
- assets
- Used for images, place your images in this folder
- pages
- actual page content
- templates
- templates you can use to base other material on
And one special file called nav.adoc
this file is (at least in the user manual) partially generated you will see a start and endtag in this file, do not add new pages between it, it will be overwritten in the next build.
The nav.adoc
is used to generate the list on the left hand side of the documentation website.
Build
Tools used
For the website build Antora is used to generate the documents.
We also generate a pdf-book using a Asciidoctor maven project.
Website
The content in this repository is used to generate the website User Manual and Technical Documentation each commit in master triggers a jenkins build that pushes the latest changes to the website. Testing the website version before deployment is currently not possible
PDF Book
The same content is used to generate a book version of the manual that can be downloaded or distributed with the installation of hop (currently under discussion)
The book can be generated using maven.
mvn clean install
The final result can be found in following location:
hop-user/tech-manual/modules/asciidoctor/target/generated-docs
Contributing
Changing existing content
- create a fork of our repository
- update a page
- check if book lay-out does not break
- create pull request
Adding a new page
When creating a new page following must be taken into account:
- add your new page to nav.adoc
- add your new page to asciidoctor index.adoc
- when using xref to link to other Antora pages add a tag website-links[]
For more information take a look at our Contribution Guide or feel free to ask us question on our Chat