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-glv Commit: 233980256400ef7e049b0550bf007cdff135b5c9 Parents: b2ef0d4 Author: Stephen Mallette <[email protected]> Authored: Mon Jun 5 07:42:56 2017 -0400 Committer: Stephen Mallette <[email protected]> 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 [email protected] 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 [email protected] 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]]
