lunes, noviembre 19, 2018

Continuous Documentation with Antora and Travis

Antora is a documentation pipeline that enables docs, product, and engineering teams to create, manage, remix, and publish documentation sites composed in AsciiDoc and sourced from multiple versioned content repositories.

You can see several examples out there from Couchbase documentation to Fedora documentation. And of course, Antora documentation is used to generate Antora documentation. You can see it here.

So basically we have our project with documents in adoc format. Then what we want is regenerating the documentation every time a PR is merged to master.

In our project, we are using Travis-CI as CI server, so I am going to show you how we have done.

First of all, you need to create a .travis.yml file on the root of your project.


First, we define what we want to use. In this case docker and git.

Then in before_install section, we are detecting if we need to regenerate documentation or not.

Basically, we are going to generate documentation in two conditions:

  1. If commit message contains the word doc, then docs should be regenerated.
  2. If you have modified an adoc file from the documentation folder (or README.adoc) and the branch is master, then the docs should be regenerated.
If any of these conditions are met, then we configure git client with user, email and token to be used for pushing the generated documentation. Notice that this information comes from environment variable defined in Travis console. Also, it is important to note that the documentation should be generated in gh-pages branch (since we are releasing to GitHub pages). For this reason, we are using git worktree which checkouts the gh-pages branch in gh-pages directory.

Then in script section, we are just using Antora docker image to render documentation.

Finally, we just need to enter into gh-pages directory, create a .nojekyll file to avoid Git Hub Pages thinks that this is a Jekyll site, and finally push the changes.

And then for PR merged, the documentation is automatically regenerated and published.

Important: This script is based on one done previously by Bartosz Majsak (@majson) for Asciidoctor. My task has been only adapting it to use Antora.

We keep learning,
Alex.

Y no me importa nada nada (nada), Que rías o que sueñes, que digas o que hagas, Y no me importa nada, Por mucho que me empeñe, estoy jugando y no me importa nada (No me importa nada - Luz  Casal)








7 comentarios:

yanmaneee dijo...

kd 11 shoes
yeezy boost 350
lebron 15
nike sneakers
supreme
hermes belt
curry 6
nike react
nike sneakers for men
kd 11

Andrew303john dijo...

Economics Assignment Help

We Fullassignment.com is among the best companies on the Economics assignment writing market. We offer top-notch essays, Business Economics Assignment help research papers, thesis and other types of works that can be assigned to you at a high school or college. We also provide Analog Electrtonics Assignment Help from our experts.

https://fullassignment.com/

hrroman dijo...

If you are looking for the Marketing Assignments help then in this case you can opt for our Market Analysis Assignment.we provide the best Assignment Help Experts.We also provide 5c Marketing Assignment for students across the globe. for more information contact us +16692714848.

Ace Starlit dijo...

Its a very impressive content. Thank you for sharing it. Visit:- Ace Starlit

Garika Jello dijo...

I’m impressed, I must say. Really rarely do I encounter a blog that’s both educative and entertaining, and let me tell you, you have hit the nail on the head. Your idea is outstanding; the issue is something that not enough people are speaking intelligently about. I am very happy that I stumbled across this in my search for something relating to this.

Click Here
Visit Web

SITES 2021 dijo...

Thank you. I authentically greeting your way for writing an article. I safe as a majority loved it to my bookmark website sheet list and will checking rear quite than later.
토토사이트

Diksha Rai dijo...

I read this post your post so nice and very informative post thanks for sharing this post
http://www.pinkiahuja.in/