| //// |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| //// |
| image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"] |
| |
| *x.y.z* |
| |
| :toc-position: left |
| |
| = Recipes |
| |
| image:gremlin-chef.png[width=120,float=left] All programming languages tend to have |
| link:https://en.wikipedia.org/wiki/Software_design_pattern[patterns of usage] for commonly occurring problems. Gremlin |
| is not different in that respect. There are many commonly occurring traversal themes that have general applicability |
| to any graph. Gremlin Recipes present these common traversal patterns and methods of usage that will |
| provide some basic building blocks for virtually any graph in any domain. |
| |
| Recipes assume general familiarity with Gremlin and the Apache TinkerPop™ stack. Be sure to have read the |
| link:https://tinkerpop.apache.org/docs/x.y.z/tutorials/getting-started[Getting Started] tutorial and the |
| link:https://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/[The Gremlin Console] tutorial. |
| |
| = Traversal Recipes |
| |
| include::between-vertices.asciidoc[] |
| |
| include::centrality.asciidoc[] |
| |
| include::collections.asciidoc[] |
| |
| include::connected-components.asciidoc[] |
| |
| include::cycle-detection.asciidoc[] |
| |
| include::duplicate-edge.asciidoc[] |
| |
| include::duplicate-vertex.asciidoc[] |
| |
| include::edge-move.asciidoc[] |
| |
| include::element-existence.asciidoc[] |
| |
| include::if-then-based-grouping.asciidoc[] |
| |
| include::pagination.asciidoc[] |
| |
| include::recommendation.asciidoc[] |
| |
| include::shortest-path.asciidoc[] |
| |
| include::traversal-induced-values.asciidoc[] |
| |
| include::tree.asciidoc[] |
| |
| include::olap-spark-yarn.asciidoc[] |
| |
| = Anti-Patterns |
| |
| image:gremlin-anti-gremlin.png[width=250] |
| |
| include::anti-patterns.asciidoc[] |
| |
| = Implementation Recipes |
| |
| include::style-guide.asciidoc[] |
| |
| include::traversal-component-reuse.asciidoc[] |
| |
| [[contributing]] |
| = How to Contribute a Recipe |
| |
| Recipes are generated under the same system as all TinkerPop documentation and is stored directly in the source code |
| repository. TinkerPop documentation is all link:http://asciidoc.org/[asciidoc] based and can be generated locally with |
| either link:https://tinkerpop.apache.org/docs/x.y.z/dev/developer/#building-testing[shell script/Maven] or |
| link:https://tinkerpop.apache.org/docs/x.y.z/dev/developer/#docker-integration[Docker] build commands. Once |
| changes are complete, submit a pull request for review by TinkerPop committers. |
| |
| NOTE: Please review existing recipes and attempt to conform to their writing and visual style. It may also be a good |
| idea to discuss ideas for a recipe on the link:+++https://lists.apache.org/list.html?dev@tinkerpop.apache.org+++[developer mailing list] |
| prior to starting work on it, as the community might provide insight on the approach and idea that would be helpful. |
| It is preferable that a link:https://issues.apache.org/jira/browse/TINKERPOP[JIRA issue] be opened that describes the nature |
| of the recipe so that the eventual pull request can be bound to that issue. |
| |
| IMPORTANT: Please read TinkerPop's link:https://tinkerpop.apache.org/docs/x.y.z/dev/developer/#_contributing[policy on contributing] |
| prior to submitting a recipe. |
| |
| To contribute a recipe, first clone the repository: |
| |
| [source,shell] |
| git clone https://github.com/apache/tinkerpop.git |
| |
| The recipes can be found in this directory: |
| |
| [source,shell] |
| ls docs/src/recipes |
| |
| Each recipe exists within a separate `.asciidoc` file. The file name should match the name of the recipe. Recipe names |
| should be short, but descriptive (as they need to fit in the left-hand table of contents when generated). The |
| `index.asciidoc` is the parent document that "includes" the content of each individual recipe file. A recipe file is |
| included in the `index.asciidoc` with an entry like this: `include::my-recipe.asciidoc[]` |
| |
| Documentation should be generated locally for review prior to submitting a pull request. TinkerPop documentation is |
| "live" in that it is bound to a specific version when generated. Furthermore, code examples (those that are |
| `gremlin-groovy` based) are executed at document generation time with the results written directly into the output. |
| The following command will generate the documentation with: |
| |
| [source,shell] |
| bin/process-docs.sh |
| |
| The generated documentation can be found at `target/docs/htmlsingle/recipes`. This process can be long on the first |
| run of the documentation as it is generating all of the documentation locally (e.g. reference documentation, |
| tutorials, etc). To generate just the recipes, follow this process: |
| |
| [source,shell] |
| bin/process-docs.sh -f docs/src/recipes |
| |
| The `bin/process-docs.sh` approach requires that Hadoop is installed. To avoid that prerequisite, try using Docker: |
| |
| [source,shell] |
| docker/build.sh -d |
| |
| The downside to using Docker is that the process will take longer as each run will require the entire documentation set |
| to be generated. |
| |
| The final step to submitting a recipe is to issue a link:https://help.github.com/articles/using-pull-requests/[pull request through GitHub]. |
| It is helpful to prefix the name of the pull request with the JIRA issue number, so that TinkerPop's automation between |
| GitHub and JIRA are linked. As mentioned earlier in this section, the recipe will go under review by TinkerPop |
| committers prior to merging. This process may take several days to complete. We look forward to receiving your |
| submissions! |
| |
| include::appendix.asciidoc[] |