You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by GitBox <gi...@apache.org> on 2020/08/31 15:25:21 UTC
[GitHub] [tinkerpop] spmallette opened a new pull request #1321: TINKERPOP-2392 Improved GLV starting docs
spmallette opened a new pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321
https://issues.apache.org/jira/browse/TINKERPOP-2392
This issue was about javascript but really might have applied to all GLVs. With the recent change of ae95dbe9c33b380555ee32716e56ec12b56c3f6c it seemed to make sense to expand this change to all GLVs and to improve upon it. I could have probably just CTR'd this in but thought it would be better to get some review on sample variety and syntax (as these changes will affect artifact repositories descriptions...nuget, pypi, npm...and I'm not sure there is a nice way to validate links/changes without a release deployment.
VOTE +1
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] spmallette commented on pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
spmallette commented on pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#issuecomment-683852101
@aboudreault if you have a moment to take a look at the python related doc changes to see if they would make sense to new python developer, that would be appreciated.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] aboudreault commented on a change in pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
aboudreault commented on a change in pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#discussion_r480273054
##########
File path: gremlin-python/src/main/jython/README.rst
##########
@@ -54,8 +54,65 @@ remote graph:
>>> g.V().both().name.toList()
[lop, vadas, josh, marko, marko, josh, peter, ripple, lop, marko, josh, lop]
-Please see the `reference documentation <http://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_
-at Apache TinkerPop for more information on usage.
+-----------------
+Sample Traversals
+-----------------
+
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The `Reference Documentation <https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps>`_
+describes these functions and other aspects of the TinkerPop ecosystem including some specifics on
+`Gremlin in Python <http://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript>`_ itself. Most of the
Review comment:
to fix: use #gremlin-python here?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] gugacavalieri commented on pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
gugacavalieri commented on pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#issuecomment-683899119
Looks like a big improvement :orange_heart:
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] spmallette commented on a change in pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
spmallette commented on a change in pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#discussion_r482133328
##########
File path: gremlin-python/src/main/jython/README.rst
##########
@@ -54,8 +54,65 @@ remote graph:
>>> g.V().both().name.toList()
[lop, vadas, josh, marko, marko, josh, peter, ripple, lop, marko, josh, lop]
-Please see the `reference documentation <http://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_
-at Apache TinkerPop for more information on usage.
+-----------------
+Sample Traversals
+-----------------
+
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The `Reference Documentation <https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps>`_
+describes these functions and other aspects of the TinkerPop ecosystem including some specifics on
+`Gremlin in Python <https://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_ itself. Most of the
+examples found in the documentation use Groovy language syntax in the
+`Gremlin Console <https://tinkerpop.apache.org/docs/current/tutorials/the-gremlin-console/>`_.
+For the most part, these examples should generally translate to Python with
+`some modification <https://tinkerpop.apache.org/docs/current/reference/#gremlin-python-differences>`_. Given the
+strong correspondence between canonical Gremlin in Java and its variants like Python, there is a limited amount of
+Python-specific documentation and examples. This strong correspondence among variants ensures that the general
+Gremlin reference documentation is applicable to all variants and that users moving between development languages can
+easily adopt the Gremlin variant for that language.
+
+Create Vertex
+^^^^^^^^^^^^^
+
+.. code:: python
+
+ from gremlin_python.process.traversal import T
+ from gremlin_python.process.traversal import Cardinality
+
+ id = T.id
+ single = Cardinality.single
+
+ def create_vertex(self, vid, vlabel):
+ g.addV(vlabel).property(id, vid). \
+ property(single, 'name', 'Apache'). \
+ property('lastname', 'Tinkerpop'). \ # default database cardinality
Review comment:
i wondered about that........ok will fix - thanks
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] spmallette commented on a change in pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
spmallette commented on a change in pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#discussion_r480311861
##########
File path: gremlin-python/src/main/jython/README.rst
##########
@@ -54,8 +54,65 @@ remote graph:
>>> g.V().both().name.toList()
[lop, vadas, josh, marko, marko, josh, peter, ripple, lop, marko, josh, lop]
-Please see the `reference documentation <http://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_
-at Apache TinkerPop for more information on usage.
+-----------------
+Sample Traversals
+-----------------
+
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The `Reference Documentation <https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps>`_
+describes these functions and other aspects of the TinkerPop ecosystem including some specifics on
+`Gremlin in Python <http://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript>`_ itself. Most of the
Review comment:
yes - thank you. i missed that link.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] jorgebay commented on a change in pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
jorgebay commented on a change in pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#discussion_r482083923
##########
File path: gremlin-python/src/main/jython/README.rst
##########
@@ -54,8 +54,65 @@ remote graph:
>>> g.V().both().name.toList()
[lop, vadas, josh, marko, marko, josh, peter, ripple, lop, marko, josh, lop]
-Please see the `reference documentation <http://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_
-at Apache TinkerPop for more information on usage.
+-----------------
+Sample Traversals
+-----------------
+
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The `Reference Documentation <https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps>`_
+describes these functions and other aspects of the TinkerPop ecosystem including some specifics on
+`Gremlin in Python <https://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_ itself. Most of the
+examples found in the documentation use Groovy language syntax in the
+`Gremlin Console <https://tinkerpop.apache.org/docs/current/tutorials/the-gremlin-console/>`_.
+For the most part, these examples should generally translate to Python with
+`some modification <https://tinkerpop.apache.org/docs/current/reference/#gremlin-python-differences>`_. Given the
+strong correspondence between canonical Gremlin in Java and its variants like Python, there is a limited amount of
+Python-specific documentation and examples. This strong correspondence among variants ensures that the general
+Gremlin reference documentation is applicable to all variants and that users moving between development languages can
+easily adopt the Gremlin variant for that language.
+
+Create Vertex
+^^^^^^^^^^^^^
+
+.. code:: python
+
+ from gremlin_python.process.traversal import T
+ from gremlin_python.process.traversal import Cardinality
+
+ id = T.id
+ single = Cardinality.single
+
+ def create_vertex(self, vid, vlabel):
+ g.addV(vlabel).property(id, vid). \
+ property(single, 'name', 'Apache'). \
+ property('lastname', 'Tinkerpop'). \ # default database cardinality
Review comment:
Comment block after line continuation character is not valid.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] FlorianHockmann commented on a change in pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
FlorianHockmann commented on a change in pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#discussion_r480962085
##########
File path: gremlin-dotnet/src/Gremlin.Net/Gremlin.Net.csproj
##########
@@ -42,10 +42,20 @@ http://tinkerpop.apache.org/docs/current/reference/#gremlin-server
or a remote graph provider that exposes protocols by which Gremlin.Net can connect.
-Please see the reference documentation of Apache TinkerPop for more information on usage: https://s.apache.org/pgbwu
+Please see the Reference Documentation of Apache TinkerPop for more information on usage: http://tinkerpop.apache.org/docs/current/reference
Review comment:
(nitpick) I think we can and should keep using `https` which also works for this link: https://tinkerpop.apache.org/docs/current/reference
##########
File path: gremlin-dotnet/README.md
##########
@@ -33,8 +33,22 @@ operating systems and with different .NET frameworks, such as .NET Framework and
nuget install Gremlin.Net
```
-Please see the [reference documentation][docs] at Apache TinkerPop for more information.
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The [Reference Documentation][steps] describes these functions and other aspects of the
+TinkerPop ecosystem including some specifics on [Gremlin in .NET][docs] itself. Most of the examples found in the
+documentation use Groovy language syntax in the [Gremlin Console][console]. For the most part, these examples
+should generally translate to C# with [some logical modification][differences]. Given the strong correspondence
+between canonical Gremlin in Java and its variants like C#, there is a limited amount of C#-specific
+documentation and examples. This strong correspondence among variants ensures that the general Gremlin reference
+documentation is applicable to all variants and that users moving between development languages can easily adopt the
+Gremlin variant for that language.
+
+**NOTE** that versions suffixed with "-rc" are considered release candidates (i.e. pre-alpha, alpha, beta, etc.) and thus
+for early testing purposes only.
[tk]: http://tinkerpop.apache.org
[gremlin]: http://tinkerpop.apache.org/gremlin.html
-[docs]: http://tinkerpop.apache.org/docs/current/reference/#gremlin-DotNet
\ No newline at end of file
+[docs]: http://tinkerpop.apache.org/docs/current/reference/#gremlin-dotnet
Review comment:
Just a nit and not really related to this PR, but we can also upgrade these links to HTTPS now.
##########
File path: docs/src/reference/gremlin-variants.asciidoc
##########
@@ -1215,6 +1219,57 @@ and then it can be called from the application as follows:
include::../../../gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsDslTests.cs[tags=dslExamples]
----
+[[gremlin-net-differences]]
+=== Differences
+
+The biggest difference between Gremlin in .NET and the canonical version in Java is the casing of steps. Canonical
+Gremlin utilizes `camelCase` as is typical in Java for function names, but C# utilizes `PascalCase` as it more typical
Review comment:
_utilizes `PascalCase` as it more typical_ should probably be _utilizes `PascalCase` as it **is** more typical_.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] jsumners commented on pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
jsumners commented on pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#issuecomment-683860728
I think these additions go a long way toward making the documentation clearer for secondary languages like JavaScript.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] spmallette commented on pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
spmallette commented on pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#issuecomment-684794092
I addressed all of the @FlorianHockmann suggestions - good catch with using "https" for links. I'd done that consistently elsewhere in our docs long ago but must have missed these somehow.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] spmallette merged pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
spmallette merged pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [tinkerpop] aboudreault commented on pull request #1321: TINKERPOP-2392 Improved GLV starting docs
Posted by GitBox <gi...@apache.org>.
aboudreault commented on pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#issuecomment-683915577
Yep, good docs changes. Thanks Stephen!
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org