We recently had our site-book doc generation break due to our not including it in the Travis build. The fix for a broken build seems simple enough - add it to our build process and assuming it doesn't cause build timeout issues, we should be good to go.
Beyond that, there are additional issues with the existing process. We have a step in our PR review for validating that the docs are rendering properly. I know I've gone back and corrected issues with broken images or incorrectly rendering pages at least a few times now. On one hand, we might say this is simply a matter of being better about validating documentation during the review process. That may be true, but rather than fight upstream like a salmon, I would prefer to simplify things, automate what we can, and use technology to work with us. Based on this conversation on METRON-1950 - ( https://lists.apache.org/thread.html/e2acf91efc5f51ba0e26d76b00ca02415d3c6ee0adee74a037ab2beb@%3Cdev.metron.apache.org%3E), I'd like to open up a general convo about improvements to our documentation generation. *Current Issues:* 1. Duplicated effort - have to check pages render in Github and the Doxia-generated site-book 2. Inconsistent model - what works for Github markdown may not work for Doxia, and vice versa 3. Github is part of our workflow and easy to check, Doxia requires an extra separate step - suffers unintentional bugs due to #2. 4. Images have to be manually added to the site rendering code for copying to the "images" folder, and explicit src ref replacements have to be included for all affected pages/links as well. 5. Page links and images are not validated - this currently requires manual review and intervention during PR review and whenever we create a new Metron release. 6. Failed site-book build is not validated. Broken build does not fail Travis *Options and Solutions:* 1. Otto has already brought up using Ascii doc as one option for solving a number of these issues. 2. For issue #5, we can write a scraper that validates links or use tooling like Cypress for this. 3. For issue #6, we can add site-book building to our Travis runs. It's pretty quick to generate and will catch the more egregious rendering bugs. I plan to look at this presently. Mike
