[GitHub] incubator-metron pull request #512: METRON-824 site-book generation is broke...
Github user mattf-horton commented on a diff in the pull request: https://github.com/apache/incubator-metron/pull/512#discussion_r109814348 --- Diff: metron-sensors/bro-plugin-kafka/README.md --- @@ -13,22 +13,28 @@ library for Kafka. This plugin has been tested against the latest release of librdkafka, which at the time of this writing is v0.9.4. In order to support interacting with a kerberized kafka, you will need libsasl2 installed -# curl -L https://github.com/edenhill/librdkafka/archive/v0.9.4.tar.gz | tar xvz -# cd librdkafka-0.9.4/ -# ./configure --enable-sasl -# make -# sudo make install +``` +# curl -L https://github.com/edenhill/librdkafka/archive/v0.9.4.tar.gz | tar xvz +# cd librdkafka-0.9.4/ +# ./configure --enable-sasl +# make +# sudo make install +``` Then compile this Bro plugin using the following commands. -# ./configure --bro-dist=$BRO_SRC -# make -# sudo make install +``` +# ./configure --bro-dist=$BRO_SRC +# make +# sudo make install +``` Run the following command to ensure that the plugin was installed successfully. -# bro -N Bro::Kafka -Bro::Kafka - Writes logs to Kafka (dynamic, version 0.1) +``` +# bro -N Bro::Kafka +Bro::Kafka - Writes logs to Kafka (dynamic, version 0.1) +``` --- End diff -- PR#511 offers the same, but also changes the double-backticks throughout the document into single backticks. While this usage doesn't raise an error, it does show incorrectly. Sorry we crossed wires. Apparently we both opened jiras and posted PRs exactly one minute apart! They both are sequentially numbered! --- 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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #512: METRON-824 site-book generation is broke...
Github user JonZeolla closed the pull request at: https://github.com/apache/incubator-metron/pull/512 --- 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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron issue #512: METRON-824 site-book generation is broken
Github user JonZeolla commented on the issue: https://github.com/apache/incubator-metron/pull/512 Duplicate of #511 - @mattf-horton beat me by a minute! --- 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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
Re: [GitHub] incubator-metron pull request #512: METRON-824 site-book generation is broke...
Heh! I submitted similar patch one minute ago!
Great minds must think alike :-)
--Matt
On 4/4/17, 6:22 PM, "JonZeolla" <g...@git.apache.org> wrote:
GitHub user JonZeolla opened a pull request:
https://github.com/apache/incubator-metron/pull/512
METRON-824 site-book generation is broken
## Contributor Comments
Currently, if you attempt to build the site-book on master you get the
following error:
```
ERROR OR ERRORS DETECTED:
ERROR: Header specification character (#) detected with indenting.
This is presumed to be an error, since it will render as text. If intentional,
put a period or other printable character before it.
on line: 16 in file: ./metron-sensors/bro-plugin-kafka/index.md
# curl -L
https://github.com/edenhill/librdkafka/archive/v0.9.4.tar.gz | tar xvz
```
In order to fix this I changed
`metron-sensors/bro-plugin-kafka/index.md` to use triple backticks instead of
indentation to indicate the code block. This allows it to parse properly in
GitHub MD as well as our Doxia site-book docs.
## Pull Request Checklist
Thank you for submitting a contribution to Apache Metron (Incubating).
Please refer to our [Development
Guidelines](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=61332235)
for the complete guide to follow for contributions.
Please refer also to our [Build Verification
Guidelines](https://cwiki.apache.org/confluence/display/METRON/Verifying+Builds?show-miniview)
for complete smoke testing guides.
In order to streamline the review of the contribution we ask you follow
these guidelines and ask you to double check the following:
### For all changes:
- [X] Is there a JIRA ticket associated with this PR? If not one needs
to be created at [Metron
Jira](https://issues.apache.org/jira/browse/METRON/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel).
- [X] Does your PR title start with METRON- where is the JIRA
number you are trying to resolve? Pay particular attention to the hyphen "-"
character.
- [X] Has your PR been rebased against the latest commit within the
target branch (typically master)?
### For documentation related changes:
- [X] 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
bin/generate-md.sh
mvn site:site
```
Note:
Please ensure that once the PR is submitted, you check travis-ci for
build issues and submit an update to your PR as soon as possible.
It is also recommended that [travis-ci](https://travis-ci.org) is set
up for your personal repository such that your branches are built there before
submitting a pull request.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/JonZeolla/incubator-metron METRON-824
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-metron/pull/512.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 #512
commit 5379d8c4f44f0bb10760a13cdef4618bd83803b7
Author: Jon Zeolla <zeo...@gmail.com>
Date: 2017-04-05T01:10:45Z
Use backticks instead of indentation for codeblocks
---
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-metron pull request #512: METRON-824 site-book generation is broke...
GitHub user JonZeolla opened a pull request:
https://github.com/apache/incubator-metron/pull/512
METRON-824 site-book generation is broken
## Contributor Comments
Currently, if you attempt to build the site-book on master you get the
following error:
```
ERROR OR ERRORS DETECTED:
ERROR: Header specification character (#) detected with indenting. This is
presumed to be an error, since it will render as text. If intentional, put a
period or other printable character before it.
on line: 16 in file: ./metron-sensors/bro-plugin-kafka/index.md
# curl -L https://github.com/edenhill/librdkafka/archive/v0.9.4.tar.gz
| tar xvz
```
In order to fix this I changed `metron-sensors/bro-plugin-kafka/index.md`
to use triple backticks instead of indentation to indicate the code block.
This allows it to parse properly in GitHub MD as well as our Doxia site-book
docs.
## Pull Request Checklist
Thank you for submitting a contribution to Apache Metron (Incubating).
Please refer to our [Development
Guidelines](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=61332235)
for the complete guide to follow for contributions.
Please refer also to our [Build Verification
Guidelines](https://cwiki.apache.org/confluence/display/METRON/Verifying+Builds?show-miniview)
for complete smoke testing guides.
In order to streamline the review of the contribution we ask you follow
these guidelines and ask you to double check the following:
### For all changes:
- [X] Is there a JIRA ticket associated with this PR? If not one needs to
be created at [Metron
Jira](https://issues.apache.org/jira/browse/METRON/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel).
- [X] Does your PR title start with METRON- where is the JIRA
number you are trying to resolve? Pay particular attention to the hyphen "-"
character.
- [X] Has your PR been rebased against the latest commit within the target
branch (typically master)?
### For documentation related changes:
- [X] 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
bin/generate-md.sh
mvn site:site
```
Note:
Please ensure that once the PR is submitted, you check travis-ci for build
issues and submit an update to your PR as soon as possible.
It is also recommended that [travis-ci](https://travis-ci.org) is set up
for your personal repository such that your branches are built there before
submitting a pull request.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/JonZeolla/incubator-metron METRON-824
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-metron/pull/512.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 #512
commit 5379d8c4f44f0bb10760a13cdef4618bd83803b7
Author: Jon Zeolla <zeo...@gmail.com>
Date: 2017-04-05T01:10:45Z
Use backticks instead of indentation for codeblocks
---
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
Re: Site Book
OK good. Forgot it was still going through incubation vote. Anyone have an update on status of us getting out of incubation? Last I saw, one of our mentors had said it was time. Have we made any progress? Anything I can help with? On Mar 5, 2017 10:09 AM, "Casey Stella" <ceste...@gmail.com> wrote: > Not yet, we don't have an official 0.3.1 release yet. When the voting ends > in incubatorngeneral there will be a PR to update our website with the > current one. > On Sun, Mar 5, 2017 at 14:43 Nick Allen <n...@nickallen.org> wrote: > > > Is the site book for the *official* 0.3.1 release available somewhere on > > the web? Like we made the site book available for the RCs [1]. > > > > [1] > > > > https://dist.apache.org/repos/dist/dev/incubator/metron/0.3. > 1-RC5-incubating/book-site/index.html > > >
Re: Site Book
Not yet, we don't have an official 0.3.1 release yet. When the voting ends in incubatorngeneral there will be a PR to update our website with the current one. On Sun, Mar 5, 2017 at 14:43 Nick Allen <n...@nickallen.org> wrote: > Is the site book for the *official* 0.3.1 release available somewhere on > the web? Like we made the site book available for the RCs [1]. > > [1] > > https://dist.apache.org/repos/dist/dev/incubator/metron/0.3.1-RC5-incubating/book-site/index.html >
Site Book
Is the site book for the *official* 0.3.1 release available somewhere on the web? Like we made the site book available for the RCs [1]. [1] https://dist.apache.org/repos/dist/dev/incubator/metron/0.3.1-RC5-incubating/book-site/index.html
[GitHub] incubator-metron issue #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron issue #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron issue #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[GitHub] incubator-metron pull request #454: METRON-716 site-book README.md
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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
[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 <ottobackwa...@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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---
Re: Site-Book
Okay, thanks. I suggest grabbing the text from the PR#429 introduction. From: Otto Fowler <ottobackwa...@gmail.com> Date: Monday, February 13, 2017 at 11:09 AM To: "dev@metron.incubator.apache.org" <dev@metron.incubator.apache.org>, Matt Foley <ma...@apache.org> Subject: Re: Site-Book Actually I was going to take a stab at it, but I was reviewing the error indexing stuff. Sorry to be tardy. I’ll still take a stab if you have not done it. Assign the jira to me On February 13, 2017 at 13:51:55, Matt Foley (ma...@apache.org) wrote: Assuming that I should take that as a request rather than an offer :-) , I’ve opened https://issues.apache.org/jira/browse/METRON-716 Thanks, --Matt On 2/13/17, 7:02 AM, "Casey Stella" <ceste...@gmail.com> wrote: Yes, definitely. On Mon, Feb 13, 2017 at 09:01 Otto Fowler <ottobackwa...@gmail.com> wrote: > Should Site-Book have a README.md describing the contents, how to build > etc? >
Re: Site-Book
Actually I was going to take a stab at it, but I was reviewing the error indexing stuff. Sorry to be tardy. I’ll still take a stab if you have not done it. Assign the jira to me On February 13, 2017 at 13:51:55, Matt Foley (ma...@apache.org) wrote: Assuming that I should take that as a request rather than an offer :-) , I’ve opened https://issues.apache.org/jira/browse/METRON-716 Thanks, --Matt On 2/13/17, 7:02 AM, "Casey Stella" <ceste...@gmail.com> wrote: Yes, definitely. On Mon, Feb 13, 2017 at 09:01 Otto Fowler <ottobackwa...@gmail.com> wrote: > Should Site-Book have a README.md describing the contents, how to build > etc? >
Re: Site-Book
Assuming that I should take that as a request rather than an offer :-) , I’ve
opened https://issues.apache.org/jira/browse/METRON-716
Thanks,
--Matt
On 2/13/17, 7:02 AM, "Casey Stella" <ceste...@gmail.com> wrote:
Yes, definitely.
On Mon, Feb 13, 2017 at 09:01 Otto Fowler <ottobackwa...@gmail.com> wrote:
> Should Site-Book have a README.md describing the contents, how to build
> etc?
>
Re: Site-Book
Yes, definitely. On Mon, Feb 13, 2017 at 09:01 Otto Fowler <ottobackwa...@gmail.com> wrote: > Should Site-Book have a README.md describing the contents, how to build > etc? >
Site-Book
Should Site-Book have a README.md describing the contents, how to build etc?
