metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mattf-horton <>
Subject [GitHub] incubator-metron pull request #429: METRON-660 [Umbrella] up-to-date version...
Date Mon, 30 Jan 2017 00:03:23 GMT
GitHub user mattf-horton opened a pull request:

    METRON-660 [Umbrella] up-to-date versioned documentation

    This has come out rather well, I think.  The integration is still open to discussion.
 Currently it is in a stand-alone, versioned-with-the-code sub-directory and sub-project.
 The idea is that a release manager would build the site-book (following the instructions
below), then copy it into a versioned subdirectory of the (unversioned) public site, to publish
it along with each code release.
    To build the book, do the following:
    In any git clone of incubator-metron containing the site-book subdirectory,
    cd site-book
    mvn site:site
    It only takes a few seconds.  You may now view your copy of the book in a browser by opening
`file:///your/path/to/incubator-metron/site-book/target/site/index.html`.  On a Mac, you can
just say `open target/site/index.html`
    Enjoy!  For code review purposes, the key files under site-book/ are:
    * **bin/** copies all .md files from the code directory tree into the site
tree, performs some transformations on them, and generates the nav tree structure and labels.
    * **bin/fix-md-dialect.awk** is called by ''.  It does transforms within
the text of each file, related to converting the Github-MD dialect of markdown into the doxia-markdown
    * **pom.xml** and **src/site/site.xml** are doxia boilerplate, tweaked for our specific
needs.  Thanks to @mmiklavc for his help getting these right.  Please don't squash the entire
PR, as the second commit is to his credit.
    * The rest is either routine fixes to .md file syntax, or should be self-explanatory.
    No .md files were harmed in the making of this PR!  The goal was "If it works in Github-MD,
don't edit the source .md file -- fix it in the re-writer."
    The only thing hardwired is the handling of the few image files used; that can be removed
when it becomes important.  Some may object to the awk script; if you wish to translate it
into python, I'll be more than happy to accept the PR :-)

You can merge this pull request into a Git repository by running:

    $ git pull METRON-660

Alternatively you can review and apply these changes as the patch at:

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #429
commit 287609d0713d6938aa5bc191687b37fe402fe392
Author: mattf-horton <>
Date:   2017-01-17T01:18:57Z

    METRON-660 Prototype structure for .md assembly into book with maven doxia-markdown plugin.

commit 6d0fd35526162c7b4ef0e5cbc580266ecbb0ac96
Author: Michael Miklavcic <>
Date:   2017-01-17T05:32:54Z

    Fixes to get doxia markdown gen working

commit 678e7c277eea7b9257334829feaa2de96c63c5cf
Author: mattf-horton <>
Date:   2017-01-19T08:19:00Z

    METRON-660 Working generator script and site specification.

commit 05caea22cc896f773e3175aeca7c6aac2bd38de8
Author: mattf-horton <>
Date:   2017-01-25T08:06:42Z

    METRON-660 re-write rules for indenting, to conform Github-MD to doxia-markdown.  First
draft.  Also misc fixes to markdown files.

commit 1c45318986b251faa3654f66368787ad6773df89
Author: mattf-horton <>
Date:   2017-01-28T01:15:16Z

    METRON-660 re-write rules for indenting, second generation.

commit 96755cb710a7187fd2c34f6700a0dd2a7893fcd2
Author: mattf-horton <>
Date:   2017-01-29T23:26:16Z

    METRON-660 re-write rules for links, third generation.


If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at or file a JIRA ticket
with INFRA.

View raw message