You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@metron.apache.org by ot...@apache.org on 2017/02/15 11:19:02 UTC
incubator-metron git commit: METRON-716 Add README.md to site-book
(ottobackwards) closes apache/incubator-metron#454
Repository: incubator-metron
Updated Branches:
refs/heads/master f6c253f44 -> d7147e32d
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/master
Commit: d7147e32d9f4f279bc779d4e1d39d691b43c3d35
Parents: f6c253f
Author: ottobackwards <ot...@gmail.com>
Authored: Wed Feb 15 06:02:58 2017 -0500
Committer: Otto Fowler <ot...@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
+
+