Repository: incubator-metron Updated Branches: refs/heads/Metron_0.3.1 f6c253f44 -> 7abd7e8a2
METRON-716 Add README.md to site-book (ottobackwards) closes apache/incubator-metron#454 Project: http://git-wip-us.apache.org/repos/asf/incubator-metron/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-metron/commit/d7147e32 Tree: http://git-wip-us.apache.org/repos/asf/incubator-metron/tree/d7147e32 Diff: http://git-wip-us.apache.org/repos/asf/incubator-metron/diff/d7147e32 Branch: refs/heads/Metron_0.3.1 Commit: d7147e32d9f4f279bc779d4e1d39d691b43c3d35 Parents: f6c253f Author: ottobackwards <ottobackwa...@gmail.com> Authored: Wed Feb 15 06:02:58 2017 -0500 Committer: Otto Fowler <o...@apache.org> Committed: Wed Feb 15 06:02:58 2017 -0500 ---------------------------------------------------------------------- site-book/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-metron/blob/d7147e32/site-book/README.md ---------------------------------------------------------------------- diff --git a/site-book/README.md b/site-book/README.md new file mode 100644 index 0000000..93d3a31 --- /dev/null +++ b/site-book/README.md @@ -0,0 +1,52 @@ +# Metron Site-Book documentation + +Metron's Site Book is an attempt at producing documentation that is: + +- Versioned and reviewed +- Tied to code versions +- Highly local to the code being documented + +The idea is that a release manager would build the site-book (following the instructions below), then publish it from the public [Metron site](http://metron.incubator.apache.org/) as the docs for the new released version. Older site-book versions should remain available for users that need them. + + +To build the book, do the following: + +In any git clone of incubator-metron containing the site-book subdirectory, + +``` +cd site-book +bin/generate-md.sh +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 type the following on the command line + +``` +open target/site/index.html +``` + +##Key Components: + +###bin/generate-md.sh + +- Copies all .md files from the code directory tree into the site tree +- Performs some transformations on them +- Generates the nav tree structure and labels + +###bin/fix-md-dialect.py + +- Called by 'generate-md.sh' +- Does transforms within the text of each file + - Converts the Github-MD dialect of markdown into the doxia-markdown dialect + +###pom.xml and src/site/site.xml + +- [Doxia](https://maven.apache.org/doxia/) boilerplate, tweaked for our specific needs + +
