Automate documentation publishing with Jenkins
Download as PPTX, PDF1 like960 views
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.
Automate documentation publishing with Jenkins
- 2. <About me /> Technical Lead Co-Admin TrainerCo-Organizer Michał Skowron
- 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 />
- 5. Cross-platform (Windows, Linux, Mac OS X) Extensible with plugins <About Jenkins />
- 6. Why should I care? <About Jenkins />
- 7. Jenkins can help you automate documentation delivery <About Jenkins />
- 8. <Plan /> Path to automation Local builds Remote Desktop Connection Jenkins Why Jenkins? Solution Resources Installation Configuration Plugins Jobs Usage Examples Benefits
- 9. <Path to automation /> Local builds JenkinsRemote Desktop Connection
- 10. <Local builds /> Not centralized Not automated
- 11. No centralized control <Local builds />
- 12. <Local builds /> Keeping your machine busy
- 13. <Local builds /> Different versions of the authoring tool Inconsistent output
- 14. <Local builds /> Help portal built outside the authoring tool Restricted access to the webserver
- 16. Remote Desktop Protocol <Remote Desktop Connection />
- 17. <Remote Desktop Connection /> Batch files and task scheduler
- 24. <Solution />
- 25. Windows 7 Professional SP 1 (32-bit) Intel Xeon @ 2.4 GHz 4 GB RAM 100 GB HDD <Resources />
- 26. No in-house developers < Resources />
- 27. https://bitnami.com/stack/jenkins version 1.658 Bitnami Jenkins Stack tool <Installation />
- 28. Use a Windows admin account to run Jenkins services <Installation />
- 30. <Configuration /> Number of concurrent builds Manage Jenkins > Configure System
- 31. <Configuration /> Environment variables Manage Jenkins > Configure System > Global Properties
- 32. <Configuration /> Access rights Manage Jenkins > Configure Global Security
- 33. <Configuration /> Email account for notifications Manage Jenkins > Configure System > E-mail Notification
- 34. Office 365 Problem: Handshaking security errors Solution: Enable the Transport Layer Security (TLS) in the Tomcat properties -Dmail.smtp.starttls.enable=true -Dhudson.model.DirectoryBrowserSupport.CSP= <Configuration />
- 37. Build Trigger Badge Plugin <Plugins /> Extra Columns Plugin
- 40. <Jobs /> Checkout from source control Git | SVN | CVS
- 41. <Jobs /> Build parameters Boolean | String | Choice | Text | …
- 43. <Jobs /> Script execution Windows batch Linux shell …
- 46. <Usage /> Checking the build queue
- 47. <Usage /> Viewing the build log
- 48. <Examples />
- 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
- 55. <Benefits/>
- 57. Other stuff Techwriter.pl: http://techwriter.pl/ ITCQF: http://itcqf.org/ Poland MadCap Flare User Group: https://web.facebook.com/groups/PLFUG/ Contact details Email: michal.skowron@3di-info.com LinkedIn: https://www.linkedin.com/in/michalskowron/ Resources 3di Poland SlideShare: https://www.slideshare.net/3diPoland 3di blog: http://3di.com.pl/blog/ <Info />
Editor's Notes
- #2: 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.
- #3: SLIDE 2 No notes
- #4: SLIDE 3 No notes
- #5: SLIDE 4 No notes
- #6: SLIDE 5 No notes
- #7: SLIDE 6 No notes
- #8: SLIDE 7 No notes
- #9: SLIDE 8 No notes
- #10: SLIDE 9 No notes
- #11: SLIDE 10 No notes
- #12: 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
- #13: SLIDE 12 MadCap Flare is quite heavy on resources
- #14: 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
- #15: 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
- #16: SLIDE 15 No notes
- #17: SLIDE 16 - Not handy - Slow - Only one connection possible at a time
- #18: 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
- #19: SLIDE 18 No notes
- #20: SLIDE 19 - Fast - Easy - Can be accessed via VPN
- #21: SLIDE 20 - Queueing - Build logs - Disabling/enabling builds - Scheduling - Easy access control
- #22: SLIDE 21 No notes
- #23: SLIDE 22 No notes
- #24: SLIDE 23 No notes
- #25: SLIDE 24 No notes
- #26: SLIDE 25 No notes
- #27: SLIDE 26 - We (tech writers) were on our own - No existing software delivery process to plug into
- #28: SLIDE 27 - One installation package - Easy to deploy
- #29: SLIDE 28 No notes
- #30: SLIDE 29 No notes
- #31: 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.
- #32: 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.
- #33: 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.
- #34: 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
- #35: SLIDE 34 No notes
- #36: 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
- #37: SLIDE 36 - Build-name-setter – custom build names within jobs - Date Parameter Plugin – date as a build parameter
- #38: 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
- #39: SLIDE 38 No notes
- #40: SLIDE 39 No notes
- #41: SLIDE 40 No notes
- #42: SLIDE 41 No notes
- #43: 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.
- #44: 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.
- #45: 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.
- #46: SLIDE 45 No notes
- #47: SLIDE 46 No notes
- #48: SLIDE 47 No notes
- #49: 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.
- #50: SLIDE 49 No notes
- #51: SLIDE 50 No notes
- #52: SLIDE 51 No notes
- #53: SLIDE 52 No notes
- #54: 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
- #55: SLIDE 54 No notes
- #56: SLIDE 55 No notes
- #57: SLIDE 56 No notes
- #58: SLIDE 57 No notes