[GitHub] [tinkerpop] FlorianHockmann opened pull request #1025: TINKERPOP-2119 Add C# code examples in doc as code

["FlorianHockmann (GitHub)" <gi...@apache.org>]

https://issues.apache.org/jira/browse/TINKERPOP-2119

I moved most of the code examples from the docs into C# source files from where they are now included in the docs. The examples are mostly added as tests. Although I had to disable (`skip`) most of these tests for now as they try to connect to a server running on `localhost:8182` where no server is listening in our test environment. Nevertheless, this ensures even for these disabled tests that the example code at least compiles and I could already find some more errors in these examples.

We should from now one only add C# code examples to the docs by adding them as source code and then including them in the AsciiDoc to ensure that our examples in the docs always work and always match their respective version of Gremlin.Net.

Only one C# code listing is still left directly in the docs as it includes numbers as references which are then referenced in the text below (for the lambda solution). We could of course replace these numbers simply by line numbers, but I didn't want to do that for just one example as it would break the style of the other examples.

I verified that the changes in the docs look as expected manually after generating the docs with `docker/build.sh -d` and the .NET tests all pass.

VOTE +1

[ Full content available at: https://github.com/apache/tinkerpop/pull/1025 ]
This message was relayed via gitbox.apache.org for dev@tinkerpop.apache.org

[GitHub] [tinkerpop] FlorianHockmann commented on issue #1025: TINKERPOP-2119 Add C# code examples in doc as code

["FlorianHockmann (GitHub)" <gi...@apache.org>]

> Maybe we can fix the indents in the docs post-processor and keep the code files clean...

That would of course be great. I don't think that we need to include that however in this PR, especially since we want to release next week. So, I'm going to merge this now as is.

[ Full content available at: https://github.com/apache/tinkerpop/pull/1025 ]
This message was relayed via gitbox.apache.org for dev@tinkerpop.apache.org

[GitHub] [tinkerpop] dkuppitz commented on issue #1025: TINKERPOP-2119 Add C# code examples in doc as code

["dkuppitz (GitHub)" <gi...@apache.org>]

Too bad that the indents had to be changed in the code files, but I like how the tagging works. Maybe we can fix the indents in the docs post-processor and keep the code files clean...

VOTE +1

[ Full content available at: https://github.com/apache/tinkerpop/pull/1025 ]
This message was relayed via gitbox.apache.org for dev@tinkerpop.apache.org

[GitHub] [tinkerpop] spmallette commented on issue #1025: TINKERPOP-2119 Add C# code examples in doc as code

["spmallette (GitHub)" <gi...@apache.org>]

This is good and bad at the same time. we get tested code but at the expense of readability in the docs during authoring. I guess it's more good than bad though. Do you feel like this needs to be merged for 3.4.0? 

[ Full content available at: https://github.com/apache/tinkerpop/pull/1025 ]
This message was relayed via gitbox.apache.org for dev@tinkerpop.apache.org

[GitHub] [tinkerpop] spmallette commented on issue #1025: TINKERPOP-2119 Add C# code examples in doc as code

["spmallette (GitHub)" <gi...@apache.org>]

VOTE +1

[ Full content available at: https://github.com/apache/tinkerpop/pull/1025 ]
This message was relayed via gitbox.apache.org for dev@tinkerpop.apache.org

[GitHub] [tinkerpop] FlorianHockmann closed pull request #1025: TINKERPOP-2119 Add C# code examples in doc as code

["FlorianHockmann (GitHub)" <gi...@apache.org>]

[ pull request closed by FlorianHockmann ]

[ Full content available at: https://github.com/apache/tinkerpop/pull/1025 ]
This message was relayed via gitbox.apache.org for dev@tinkerpop.apache.org

[GitHub] [tinkerpop] FlorianHockmann commented on issue #1025: TINKERPOP-2119 Add C# code examples in doc as code

["FlorianHockmann (GitHub)" <gi...@apache.org>]

I think the readability during authoring isn't that bad when you use a tool that can preview AsciiDoc like the [AsciiDoc plugin for VS Code](https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode) as it can directly include the code examples. So, at least in the preview, you won't notice the difference.
If we however find any other solution to verify the examples in the docs automatically, then we can of course also use that. I just think that we really need to verify them as they already contain errors and we currently don't really have many C# examples. If we want to add examples for the different GLVs for all steps, then this becomes a lot more important.

 > Do you feel like this needs to be merged for 3.4.0?

I would merge it for 3.4.0 simply because some examples in the docs had errors which are fixed by this. If you don't want to merge this now, then we could also compare the code examples included in source in this PR with the current version in the docs and fix them there independently of this PR for 3.4.0.

[ Full content available at: https://github.com/apache/tinkerpop/pull/1025 ]
This message was relayed via gitbox.apache.org for dev@tinkerpop.apache.org