Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

METRON-1950: Site-book generation broken in master #1309

Closed
wants to merge 1 commit into from

Conversation

Projects
None yet
2 participants
@mmiklavc
Copy link
Contributor

mmiklavc commented Dec 20, 2018

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:

  • Is there a JIRA ticket associated with this PR? If not one needs to be created at Metron Jira.
  • 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.
  • Has your PR been rebased against the latest commit within the target branch (typically master)?

For code changes:

  • Have you included steps to reproduce the behavior or problem that is being changed or addressed?

  • Have you included steps or a guide to how the change may be verified and tested manually?

  • 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?

  • 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:

  • 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
    
@anandsubbu

This comment has been minimized.

Copy link
Contributor

anandsubbu commented Dec 20, 2018

+1

Ran mvn clean site without the change and did ran into the build failure.
Applied the fix and the sitebook was generated fine. Validated the metron-parsing README in the sitebook and the contents looked fine. Thanks for the fix, @mmiklavc !

@asfgit asfgit closed this in 9e026e3 Dec 20, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.