This document discusses how to automate documentation publishing using Jenkins. It describes how Jenkins provides centralized, automated control over documentation builds and publishing. It provides examples of how Jenkins can be configured with jobs to regularly build documentation from source control and publish it to different environments like draft, test, and production servers. Using Jenkins brings benefits like freeing up authors' machines, consistent outputs, and easy access to published documentation.
4. “A self-contained,
open source automation
server which can be
used to automate all
sorts of tasks related
to building, testing,
and deploying software”
<About Jenkins />
49. Used by tech writers for authoring
No login required to run the job
Documentation hosted on a Linux webserver
Build parameters to choose
Builds from one SVN location (trunk)
Building and publishing logic in a C#
script
Scheduled to run everyday between 1-2 am
<#1 />
Publishing documentation
to the draft server
50. <#1 />
Publishing documentation
to the draft server
Send an email notification
if the build fails
Check out source
files from SVN
Execute the C# script
using provided parameter values
51. <#2 />
Publishing documentation
to the test server
Used by localization engineers for QA
Login required to run the job
Documentation hosted on a Linux webserver
Build parameters to choose
Builds from different SVN locations
(branches)
Building and publishing logic in a C#
script
No schedule
52. <#2 />
Publishing documentation
to the test server
Send an email notification
if the build fails
Check out source
files from SVN
Execute the C# script
using provided parameter values
53. <#3 />
Copying documentation from the test
server to the production server
Used by localization engineers for
publishing
Login required to run the job
Documentation hosted on a Linux webserver
Build parameters to choose
Copying logic in a Windows batch file
No schedule
54. <#3 />
Copying documentation from the test
server to the production server
Check out source
files from SVN
Execute the Windows batch file
using provided parameter values
SLIDE 1
You don’t need to jump immediately at creating a solution for the entire department of 100 people. You can find a small project and automate documentation publishing for a few authors. And Jenkins can help you with that.
SLIDE 2
No notes
SLIDE 3
No notes
SLIDE 4
No notes
SLIDE 5
No notes
SLIDE 6
No notes
SLIDE 7
No notes
SLIDE 8
No notes
SLIDE 9
No notes
SLIDE 10
No notes
SLIDE 11
- No queueing
- No build log – who built what and when
- No possibility to disable builds
- No schedule – it’s possible to schedule a batch target in Flare (scheduled builds are created using the Windows Task Scheduler) but you’re machine must be on to run a scheduled task
SLIDE 12
MadCap Flare is quite heavy on resources
SLIDE 13
- Different versions of MadCap Flare – although versions are compatible, there may be differences in building logic
- Inconsistent output – layout and formatting problems, like missing fonts
SLIDE 14
1. Help portal built outside the authoring tool
- Authoring done in Flare
- Content styled and formatted on the web server – need to upload it to the target web server to view the real styling
2. Restricted access to the server
- Firewall - connection to the server possible only from the office, some people work remotely and the access didn’t work through VPN
- Login required - login credentials are stored locally on a machine, not in a Flare project. It wasn’t possible to commit them to source control. Everyone had to provide credentials individually on their machine
SLIDE 15
No notes
SLIDE 16
- Not handy
- Slow
- Only one connection possible at a time
SLIDE 17
- No queueing mechanism for manually triggered builds
- No management options (disabling builds) – info left in notepad “Don’t touch the batch files”
- No easy overview of what was run and when
SLIDE 26
- We (tech writers) were on our own
- No existing software delivery process to plug into
SLIDE 27
- One installation package
- Easy to deploy
SLIDE 28
No notes
SLIDE 29
No notes
SLIDE 30
This setting defines how many building processes can run at the same time. Keep this number at a reasonable level, not to overload the building server. It’s especially important in case of a low-budget server that doesn’t offer outstanding performance. If you start more processes than defined by this parameter, Jenkins will queue them for execution.
SLIDE 31
Custom variables for things that can be reused in different parts of Jenkins.
A good candidate for a variable would be a path to an application, for example, to your help authoring tool.
The variable is defined in the Jenkins settings and can be used in jobs. This way you don't have to type in the path in each job you configure. When the path changes for some reason (e.g. you move the Flare installation folder to a different location), you don't have to update the path in every job where it's used.
SLIDE 32
You may need to limit what certain users can do and to leave full control to the administrator. One of the options is to let everyone start the building process and see the log entries, but to allow only admins to change the system configuration. Jenkins has quite a robust set of permissions that you can adjust.
SLIDE 33
- Jenkins offers a basic email notification mechanism that offers a very limited set of options
- If you need more options, you need a plugin – mentioned on the next slide
SLIDE 34
No notes
SLIDE 35
- ThinBackup – scheduled or on-demand backups of the Jenkins configuration, possibility to restore from backups
- Email Extension plugin - custom email notifications, you can define the content, recipients, triggers on the system and job level
SLIDE 36
- Build-name-setter – custom build names within jobs
- Date Parameter Plugin – date as a build parameter
SLIDE 37
- Build Trigger Badge plugin - icons in the build history identifying manual and automatic builds
- Extra Columns Plugin – additional columns in a list view
SLIDE 38
No notes
SLIDE 39
No notes
SLIDE 40
No notes
SLIDE 41
No notes
SLIDE 42
You can start jobs manually or schedule them to start automatically. For example, you can set up a job to start every day between 1 and 2 am.
This field follows the syntax of cron (with minor differences). Specifically, each line consists of 5 fields separated by TAB or whitespace:
- MINUTE
- HOUR
- DAY OF MONTH
- MONTH
- DAY OF WEEK
To allow periodically scheduled tasks to produce even load on the system, the symbol H (for “hash”) should be used wherever possible. For example, using 0 0 * * * for a dozen daily jobs will cause a large spike at midnight. In contrast, using H H * * * would still execute each job once a day, but not all at the same time, better using limited resources.
SLIDE 43
You can couple Jenkins with any documentation tool that supports building output from the command-line interface (CLI), like static site generators and API documentation generators. If you prefer not to use Windows batch commands, you can install plugins for scripting languages, like Python.
SLIDE 44
You can also configure a job to perform a post-build action after the main building steps finish. For example, you can tell Jenkins to send you an email notification with the log attached to it each time the job doesn’t complete successfully.
SLIDE 45
No notes
SLIDE 46
No notes
SLIDE 47
No notes
SLIDE 48
We have three servers:
- Draft
- Test
- Production
Authors work on the draft server, localization engineers QA content on the test server.
When the content is translated and ready for release, localization engineers copy the content from the test to production server.
SLIDE 49
No notes
SLIDE 50
No notes
SLIDE 51
No notes
SLIDE 52
No notes
SLIDE 53
Copying logic in a Windows batch file:
- Log in via PuTTy to create a backup in ZIP format
- Rsync the test and productions folders
- Log in via WinSCP to download the backup file
- Use Windows copy to put the downloaded backup on a network share