mmiklavc opened a new pull request #1309: METRON-1950: Site-book generation broken in master URL: https://github.com/apache/metron/pull/1309 ## Contributor Comments https://issues.apache.org/jira/browse/METRON-1950 This is currently breaking the ability the run `mvn clean site` in the site-book module. The reason for this issue is that we recently had a PR make it in that likely looked good via Github markdown, but didn't end up getting tested via Doxia using our site-book build. The errors end up being really esoteric, e.g. it will complain about opening/closing tags. In reality, this stemmed from a few nested problems. First, indentation around some code samples (triple backticks) within bullet lists was incorrect. This cause the open/close tag error. Even if you fix that, the html page will render horribly. You can try all the nested indexing for 2nd level bullet list code examples you want, but it will never work until you correct the full chain. The Doxia plugin is extremely opinionated about having 4 spaces for nesting indented bullet list along with any other comments or code examples that should be indented at the same level. Items that should end up at the same indention level as a bullet point actually need another 4 spaces of indentation. You can see examples in the README's in this PR. A sample follows: ``` * Test1 * Test1a I'm a comment within Test1a ``` { "foo" : "bar", "this" : "is a code example with json" } ``` I'm at the same level as Test1a, a non-bullet item under Test1 * Test2 * Test2a ``` This would render as follows: * Test1 * Test1a I'm a comment within Test1a ``` { "foo" : "bar", "this" : "is a code example with json" } ``` I'm at the same level as Test1a, a non-bullet item under Test1 * Test2 * Test2a I generally add 1 extra blank line above and below the indented code snippets for better spacing, but I believe that's optional and shouldn't affect the overall document formatting, unlike the indentation. I also fixed a couple broken images in the parsers README and use-cases README for parser-chaining. The upshot to this part of the fix is that you need to make sure you update the rewriting rules to include the original image path, and then rewrite and project-relative links accordingly in each markdown page using the relative path to "images", which is where the site-book copies them all. **Testing** Run the site-book documentation validation steps in our PR checklist from below. * Check formatting and images on the main parser page - metron-platform/metron-parsing/index.html * Check broken images on metron-platform/metron-parsing/metron-parsers-common/ParserChaining.html * Check I didn't break any images in use-cases/parser_chaining/index.html ## Pull Request Checklist ### For all changes: - [x] Is there a JIRA ticket associated with this PR? If not one needs to be created at [Metron Jira](https://issues.apache.org/jira/browse/METRON/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel). - [x] Does your PR title start with METRON-XXXX where XXXX is the JIRA number you are trying to resolve? Pay particular attention to the hyphen "-" character. - [x] Has your PR been rebased against the latest commit within the target branch (typically master)? ### For code changes: - [x] Have you included steps to reproduce the behavior or problem that is being changed or addressed? - [x] Have you included steps or a guide to how the change may be verified and tested manually? - [x] Have you ensured that the full suite of tests and checks have been executed in the root metron folder via: ``` mvn -q clean integration-test install && dev-utilities/build-utils/verify_licenses.sh ``` - n/a Have you written or updated unit tests and or integration tests to verify your changes? - n/a If adding new dependencies to the code, are these dependencies licensed in a way that is compatible for inclusion under [ASF 2.0](http://www.apache.org/legal/resolved.html#category-a)? - n/a Have you verified the basic functionality of the build by building and running locally with Vagrant full-dev environment or the equivalent? ### For documentation related changes: - [x] Have you ensured that format looks appropriate for the output in which it is rendered by building and verifying the site-book? If not then run the following commands and the verify changes via `site-book/target/site/index.html`: ``` cd site-book mvn site ```
---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
