tinkerpop git commit: Improved dev docs on Documentation contributions CTR

[sp...@apache.org]

Repository: tinkerpop
Updated Branches:
  refs/heads/tp32 b2ef0d43a -> 233980256


Improved dev docs on Documentation contributions CTR


Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/23398025
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/23398025
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/23398025

Branch: refs/heads/tp32
Commit: 233980256400ef7e049b0550bf007cdff135b5c9
Parents: b2ef0d4
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Mon Jun 5 07:42:56 2017 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Mon Jun 5 07:42:56 2017 -0400

----------------------------------------------------------------------
 docs/src/dev/developer/contributing.asciidoc    | 29 ++++++++++++++++----
 .../developer/development-environment.asciidoc  | 18 +++++++++++-
 2 files changed, 41 insertions(+), 6 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/23398025/docs/src/dev/developer/contributing.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/developer/contributing.asciidoc b/docs/src/dev/developer/contributing.asciidoc
index 847a353..b233dbd 100644
--- a/docs/src/dev/developer/contributing.asciidoc
+++ b/docs/src/dev/developer/contributing.asciidoc
@@ -68,11 +68,30 @@ review process.
 Writing Documentation
 ~~~~~~~~~~~~~~~~~~~~~
 
-TinkerPop has a robust documentation system that is based on link:http://asciidoc.org/[asciidoc]. Proposing a
-documentation change is quite similar to providing a source code change, which is described below in more detail.
-Note that there is a difference between project documentation and the TinkerPop web site. Changes to
-project documentation can be performed via pull request, but only TinkerPop committers can make web site changes.
-Feel free to propose web site changes on the dev@tinkerpop.apache.org mailing list.
+Proposing a documentation change is quite similar to providing a source code change, which is described below in more
+detail. Note that there is a difference between project documentation and the TinkerPop web site. The project
+documentation refers to the documentation that is published per release like, tutorials, reference documentation, and
+other similar pages. This content is not updated after release and remains static bound to that version. The TinkerPop
+web site refers to the static home page and its related content, such as link:http://tinkerpop.apache.org/gremlin.html[Understanding Gremlin],
+link:http://tinkerpop.apache.org/policy.html[Provider Listing and Graphic Usage Policies] and other similar pages.
+This content is not bound to any particular version and can be published at any time where new content simply replaces
+old content.
+
+For both types of documentation, changes can be submitted via pull request. For project documentation, TinkerPop has
+a robust documentation system that is based on link:http://asciidoc.org/[asciidoc]. The content can be found in the
+link:https://github.com/apache/tinkerpop/tree/master/docs/src[docs/src]. Recall that this documentation is version
+specific, so consider the appropriate branch on which to submit the pull request so that the documentation is reflective
+of the version it is tied to. To view generated documentation locally, read more about environment configurations in
+the <<documentation-environment,Documentation Environment>> section.
+
+For web site changes, the process is largely the same except that the documentation system is HTML based instead of
+Asciidoc. The content can be found in the source control tree at link:[https://github.com/apache/tinkerpop/tree/master/docs/site[docs/site].
+The web site is always published from the `master` branch as it is not bound to a version, so there is no need to
+submit a pull request to any other branches besides that one. If the change to this documentation involves changing
+provider listings in some way, first propose the those changes on the dev@tinkerpop.apache.org mailing list and achieve
+consensus (wait time is 72 hours as usual). At that point, pull requests or direct changes can be submitted.
+Again, see the <<documentation-environment,Documentation Environment>> section for more information on how to generate
+the site locally.
 
 Reporting Bugs
 ~~~~~~~~~~~~~~

http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/23398025/docs/src/dev/developer/development-environment.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/developer/development-environment.asciidoc b/docs/src/dev/developer/development-environment.asciidoc
index 98a89f7..2dff247 100644
--- a/docs/src/dev/developer/development-environment.asciidoc
+++ b/docs/src/dev/developer/development-environment.asciidoc
@@ -58,6 +58,22 @@ to set the `CLASSPATH` to point at the directory containing the Hadoop configura
 
 Also note that link:http://www.grymoire.com/Unix/Awk.html[awk] version `4.0.1` is required for documentation generation.
 
+Documentation can be generated locally with:
+
+[source,text]
+bin/process-docs.sh
+
+Documentation is generated to the `target/docs` directory. It is also possible to generate documentation locally with
+Docker. `docker/build.sh -d`.
+
+To generate the web site locally, there is no need for any of the above infrastructure. Site generation is a simple
+shell script:
+
+[source,text]
+bin/generate-home.sh
+
+The site will be generated to the `target/site/home` directory.
+
 [[python-environment]]
 Python Environment
 ~~~~~~~~~~~~~~~~~~
@@ -82,7 +98,7 @@ test is configured by a "console-integration-tests" Maven profile. This profile
 simply piggy-back on the `.glv` file in `gremlin-python`. Note that unlike `gremlin-python` the tests are actually
 integration tests and therefore must be actively switched on with `-DskipIntegrationTests=false`:
 
-[source,text
+[source,text]
 mvn clean install -pl gremlin-console -DskipIntegrationTests=false
 
 [[release-environment]]