GitHub user mattf-horton opened a pull request:
https://github.com/apache/incubator-metron/pull/429
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
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 say `open target/site/index.html`
Enjoy! For code review purposes, 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.
* **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 :-)
Thanks,
--Matt
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/mattf-horton/incubator-metron METRON-660
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-metron/pull/429.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 #429
----
commit 287609d0713d6938aa5bc191687b37fe402fe392
Author: mattf-horton <mfo...@hortonworks.com>
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 <michael.miklav...@gmail.com>
Date: 2017-01-17T05:32:54Z
Fixes to get doxia markdown gen working
commit 678e7c277eea7b9257334829feaa2de96c63c5cf
Author: mattf-horton <mfo...@hortonworks.com>
Date: 2017-01-19T08:19:00Z
METRON-660 Working generator script and site specification.
commit 05caea22cc896f773e3175aeca7c6aac2bd38de8
Author: mattf-horton <mfo...@hortonworks.com>
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 <mfo...@hortonworks.com>
Date: 2017-01-28T01:15:16Z
METRON-660 re-write rules for indenting, second generation.
commit 96755cb710a7187fd2c34f6700a0dd2a7893fcd2
Author: mattf-horton <mfo...@hortonworks.com>
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
