You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/08/04 22:20:58 UTC
[3/4] isis git commit: ISIS-1082: minor updates to docs describing
how to generate docs.
ISIS-1082: minor updates to docs describing how to generate docs.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/37e42b2a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/37e42b2a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/37e42b2a
Branch: refs/heads/master
Commit: 37e42b2a25690687a05e96b4cdbf8bae879fc4ed
Parents: a197924
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Aug 4 08:12:57 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Aug 4 08:12:57 2015 +0100
----------------------------------------------------------------------
adocs/documentation/monitor.sh | 2 +-
.../src/main/asciidoc/guides/_cg_asciidoc.adoc | 32 +++++++-------------
2 files changed, 12 insertions(+), 22 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/37e42b2a/adocs/documentation/monitor.sh
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.sh b/adocs/documentation/monitor.sh
index bf5ff7b..2a448c1 100644
--- a/adocs/documentation/monitor.sh
+++ b/adocs/documentation/monitor.sh
@@ -1,2 +1,2 @@
#!/usr/bin/env bash
-mvn clean compile && ruby monitor.rb
+mvn clean compile && ruby monitor.rb -b
http://git-wip-us.apache.org/repos/asf/isis/blob/37e42b2a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc
index ed4de95..bc9015d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc
@@ -76,7 +76,9 @@ You could then use a web server such as Python's SimpleHTTPServer to preview (so
== Instant Rebuild (using Ruby)
-The ruby script, `monitor.rb` emulates the `mvn site` command, regenerating any changed Asciidoctor files to the relevant `target/site` directory. If any included files are changed then it rebuilds the parent (per the above naming convention).
+The ruby script, `monitor.rb` emulates the `mvn compile` command, regenerating any changed Asciidoctor files to the relevant `target/site` directory. Moreover if any included files are changed then it rebuilds the parent (per the above naming convention).
+
+=== One-time setup
To setup:
@@ -89,7 +91,7 @@ To setup:
We use Ruby 2.0 rather than 2.1 because the wdm gem (required to monitor the filesystem if running on Windows) is not currently compatible with Ruby 2.1.
====
-To install:
+To download the required Ruby dependencies, use:
[source,bash]
----
@@ -97,23 +99,18 @@ gem install bundler
bundle install
----
+=== Instant Rebuild
+
To run, we typically just use:
[source,bash]
----
-ruby monitor.rb
+sh monitor.sh
----
-This will start monitoring all files under `src/main/asciidoc`, and start up a web server on port 4000 so you can review results. If any `.adoc` changes, then the appropriate HTML will be regenerated. And, if any new assets (CSS, images etc) are added, they will be copied across.
-
-It often makes sense to combine this with `mvn`:
-
-[source,bash]
-----
-mvn clean install && ruby monitor.rb
-----
+This script simply runs `mvn clean compile && ruby monitor.rb -b`. The `mvn` command performs a clean rebuild of the site, and then the ruby script monitors for any further changes under `src/main/asciidoc`.
-This directory contains a tiny script, `r.sh`, that executes exactly the above line.
+The script also starts up a web server on port 4000 so you can review results. If any `.adoc` changes, then the appropriate HTML will be regenerated. And, if any new assets (CSS, images etc) are added, they will be copied across. The `-b` flag passed through means that the script also starts a web browser pointing at the newly generated docs.
The `monitor.rb` script has a couple of other options, use `-h` flag for usage:
@@ -133,8 +130,6 @@ usage: monitor.rb [options]
----
-
-
== Publish procedure
Only Apache Isis committers can publish to link:http://isis.apache.org[isis.apache.org]. We've decided to include these procedures here here (rather than put them in the xref:cg.adoc#_cg_committers[committers' section] of this guide, just to keep things together.
@@ -188,15 +183,10 @@ To copy and to also commit the generated documents to the `isis-site.git` repo ,
[source,bash]
----
-mvn clean install
+sh publish.sh "ISIS-nnnn: a custom commit message"
----
-This will use a standard commit message (in the `isis-site.git` repo). If you want to specify a custom message, use:
-
-[source,bash]
-----
-mvn clean install -Dmessage="ISIS-nnnn: a custom commit message"
-----
+Behind the scenes this just calls `mvn clean install -Dmessage=...`.
Pushing the commits (in the `isis-site.git` directory, of course) will publishing the changes: