You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@metron.apache.org by ottobackwards <gi...@git.apache.org> on 2017/02/13 20:56:32 UTC
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
GitHub user ottobackwards opened a pull request:
https://github.com/apache/incubator-metron/pull/454
METRON-716 site-book README.md
Initial draft of a readme for site-book documentation.
Questions: should we list the tools used more explicitly?
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/ottobackwards/incubator-metron METRON-716
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-metron/pull/454.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #454
----
commit f56190441f4751bc2493b49b1495258ed0a25c5b
Author: Otto Fowler <ot...@gmail.com>
Date: 2017-02-13T20:54:26Z
initial draft of site-book README.md
----
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by mattf-horton <gi...@git.apache.org>.
Github user mattf-horton commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100911935
--- Diff: site-book/README.md ---
@@ -0,0 +1,51 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+- Versioned and reviewed,
+- Only committers can edit
--- End diff --
I would recommend deleting "only committers can edit". It is actually self-evident, and seems unnecessary to state as a primary objective. The other three are tremendously more important.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by mattf-horton <gi...@git.apache.org>.
Github user mattf-horton commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100912944
--- Diff: site-book/README.md ---
@@ -0,0 +1,51 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+- Versioned and reviewed,
+- Only committers can edit
+- Tied to code versions
+- Highly local to the code being documented
+
+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.
--- End diff --
suggest instead this sentence to read:
"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."
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100898592
--- Diff: site-book/README.md ---
@@ -0,0 +1,42 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+-Versioned and reviewed,
--- End diff --
Probably want to put a space between -V and remove the comma at the end to get:
\- Versioned and reviewed
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100936433
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# 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:
--- End diff --
Add two spaces to the end of this line to ensure the next line says separate post-parsing. I think you can also just add second newline between them.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100899291
--- Diff: site-book/README.md ---
@@ -0,0 +1,42 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+-Versioned and reviewed,
+- Only committers can edit
+- Tied to code versions
+- Highly local to the code being documented
+
+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
+ 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
+
+The key files under site-book/ are:
+
+###bin/generate-md.sh
+
+- 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.
--- End diff --
I suggest changing this to:
- 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
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100899551
--- Diff: site-book/README.md ---
@@ -0,0 +1,42 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+-Versioned and reviewed,
+- Only committers can edit
+- Tied to code versions
+- Highly local to the code being documented
+
+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
+ 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
+
+The key files under site-book/ are:
+
+###bin/generate-md.sh
+
+- 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 'generate-md.sh'. It does transforms within the text of each file, related to converting the Github-MD dialect of markdown into the doxia-markdown dialect.
--- End diff --
I suggest changing this to:
- Called by `generate-md.sh`
- Performs transforms within the text of each file into the doxia-markdown dialect (related to converting the Github-MD dialect of markdown).
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100899029
--- Diff: site-book/README.md ---
@@ -0,0 +1,42 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+-Versioned and reviewed,
+- Only committers can edit
+- Tied to code versions
+- Highly local to the code being documented
+
+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
+ bin/generate-md.sh
+ mvn site:site
--- End diff --
Perhaps should wrap in ``` for consistency? I think that's how we do it in our other READMEs.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by mattf-horton <gi...@git.apache.org>.
Github user mattf-horton commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100912086
--- Diff: site-book/README.md ---
@@ -0,0 +1,51 @@
+# Site Book Metron documentation
--- End diff --
Suggest "Metron Site-Book documentation"
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100899087
--- Diff: site-book/README.md ---
@@ -0,0 +1,42 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+-Versioned and reviewed,
+- Only committers can edit
+- Tied to code versions
+- Highly local to the code being documented
+
+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
+ 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.
--- End diff --
Remove the trailing .
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron issue #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on the issue:
https://github.com/apache/incubator-metron/pull/454
+1 (non-binding) by inspection. Thanks for putting this together Otto, good catch.
On a related note, it looks like Travis is either backed up or having an issue. Another PR which is a couple of hours old also hasn't started yet.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100936871
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# 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
+```
+
+The key files under site-book are:
+
+###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.awk
+
+- Is called by 'generate-md.sh'
+- It does transforms within the text of each file
--- End diff --
Suggest changing this into:
- Called by `generate-md.sh`
- Does transforms within the text of each file
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by mattf-horton <gi...@git.apache.org>.
Github user mattf-horton commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100938289
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# 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.
--- End diff --
Please do.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r101099598
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# 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.
--- End diff --
Done.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100935685
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# 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
+```
+
+The key files under site-book are:
+
+###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.awk
--- End diff --
This was migrated to python and is now `bin/fix-md-dialect.py`.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100935985
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# Metron Site-Book documentation
+
+Metron's Site Book is an attempt at producing documentation that is
--- End diff --
Maybe I'm being a bit of a pedant, but I would put a \: at the end of this line.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100950331
--- Diff: site-book/README.md ---
@@ -1,13 +1,14 @@
# Metron Site-Book documentation
-Metron's Site Book is an attempt at producing documentation that is
+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:
--- End diff --
I meant adding an additional newline at the end of this line. If you [view this line](https://github.com/ottobackwards/incubator-metron/blob/31b517aeea1e4afb73e45910db523c2660aa8584/site-book/README.md) post-parsing you'll see lines 12 and 13 are both together right now.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100899121
--- Diff: site-book/README.md ---
@@ -0,0 +1,42 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+-Versioned and reviewed,
+- Only committers can edit
+- Tied to code versions
+- Highly local to the code being documented
+
+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
+ 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
--- End diff --
Wrap in ``` ?
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/incubator-metron/pull/454
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100936703
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# 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
+```
+
+The key files under site-book are:
--- End diff --
I would suggest changing this into
## Key components
However, either way, I'm fine with it.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by mattf-horton <gi...@git.apache.org>.
Github user mattf-horton commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100910894
--- Diff: site-book/README.md ---
@@ -0,0 +1,51 @@
+# Site Book Metron documentation
+
+Metron's Site Book is an attempt at producing documentation that is
+
+- Versioned and reviewed,
+- Only committers can edit
+- Tied to code versions
+- Highly local to the code being documented
+
+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
--- End diff --
need a newline after the triple-backtick.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100936329
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# 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.
--- End diff --
Do we actually have a process for the release manager to follow that includes this? It should probably exist [here](https://cwiki.apache.org/confluence/display/METRON/Release+Process). If I'm not missing it, I will happily suggest an update to the wiki via the dev list.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron issue #454: METRON-716 site-book README.md
Posted by mattf-horton <gi...@git.apache.org>.
Github user mattf-horton commented on the issue:
https://github.com/apache/incubator-metron/pull/454
+1 More than okay! This is great, thanks for doing it.
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/incubator-metron/pull/454#discussion_r100935773
--- Diff: site-book/README.md ---
@@ -0,0 +1,50 @@
+# 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
+```
+
+The key files under site-book are:
+
+###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.awk
+
+- Is called by 'generate-md.sh'
+- It 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 boilerplate, tweaked for our specific needs.
--- End diff --
Doxia should be capitalized, maybe also link to https://maven.apache.org/doxia/
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron issue #454: METRON-716 site-book README.md
Posted by ottobackwards <gi...@git.apache.org>.
Github user ottobackwards commented on the issue:
https://github.com/apache/incubator-metron/pull/454
@mattf-horton are you ok on this after the revisions?
---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---