第 29 章促进 Neo4j 发展

优质

小牛编辑

125浏览

2023-12-01

Neo4j工程是一个致力于带给我们快速复杂数据存储的开源工程。任何形式的帮助都是社区高度赞赏的 - 你不是一个人在战斗，请参考：贡献者列表!

贡献给Neo4j工程的一个关键方面，请参考：CLA协议。

简而言之：确保签署CLA协议并通过邮件发送给我们否则Neo4j工程不能接收你的贡献信息。

注意你也能贡献文档或者在当前页面提出你的反馈来给社区做贡献。基本上，在你能得到帮助的任何地方，都有你贡献的机会。

如果你想为社区作贡献，可以从一些好的领域开始，特别要与社区联系，请参考：社区支持。

如果你想在文档方面作贡献，我们非常推荐你先阅读：社区文档。

29.1. 贡献者许可协议

我们要求所有托管在Neo4j上面的源代码都必须通过 Neo4j Contributor License Agreement (CLA)贡献出来。这个协议的目的是为了保护完整的代码库，反过来也保护代码库周围的社区：创始公司Neo Technology，Neo4j开发社区以及Neo4j用户。贡献者协议类型跟很多开源软件和开源工程类似（实际上，他非常类似于广泛签署的 Oracle Contributor Agreement）。

如果你没有CLA协议的其他任何问题，请继续浏览下面的内容或者发送邮件到地址： admins@neofourjay.org 。如果你有一个法律问题，请咨询律师。

29.1.2. 一般问题我会失去我自己代码的权利吗？

你们会如何处理我贡献的东西？

我们可以行使版权持有人的所有权利，以及拥有您在Neo4j CLA中授权给我们的你拥有的权利。在CLA提供的联合版权的所有权中，在你的贡献上，你可行使和我们相同的权利。

为此社区会提供什么福利？

嗯，它可以让我们赞助Neo4j重点项目和为社区提供基础设施，以便缺博啊我们能引入这些到软件中，我们发送给我们的客户没有任何讨厌的惊喜。没有这个能力，我们作为一个小公司将很难发布我们所有的代码作为免费软件。

而且，CLA协议让阿功能我们保护社区成员（包括开发者和用户）在有需要时面对有敌意的知识产品诉讼。这是与其他自由软件管家维护项目（除了与自由软件基金会（FSF），没有共享的版权而是你完全签署的FSF）是一样的，比如 Free Software Foundation - FSF。贡献者协议页包括一份"自由软件公约"或者说一个承诺：贡献的东西将保持作为免费软件。

直到最后，你仍然保留你的贡献的所有权利而我们非常有信息的说：我们能保护Neo4j社区以及Neo4j公司的客户。

我们可以讨论一些CLA里面的条款吗？

绝对可以的！请告诉我们你的反馈！But let’s keep the legalese off the mailing lists。请把你的反馈信息直接发送邮件到 cla (@t) neotechnology.com，我们会尽快回复你的。

我仍然不喜欢CLA协议。

好的，当然你也可以把你的代码或者稳定托管到其他任何地方。请不要！我们只是在这讨论下我们提供的基础设施的规则而已。

29.1.3. 如何签署CLA协议

当你已经阅读完了CLA，请你发送一份邮件到：cla (@t) neotechnology.com。包括下面一些信息：

你的完整姓名（包括中文名和英文名）。

你的常用电子邮件。

Neo4j CLA协议的一份拷贝作为附件发送。

你同意这个协议的表述。

举个例子：

Hi. My name is John Doe (john@doe.com).

29.2. 可以贡献的领域

29.2.1. Neo4j发布

29.2.2. 维护Neo4j文档

29.2.3. Neo4j的客户端驱动以及绑定

Neo4j是一个高速成长并有大量贡献空间的项目。在这里你可以和全情投入，当然取决于你的时间，技能和兴趣。下面是一些你可能感兴趣的领域：

29.2.1. Neo4j发布

Neo4j社区版问题讨论，适合刚开始为社区作贡献的成员。

查看 GitHub Neo4j项目获取所有的Neo4j工程。

29.2.2. 维护Neo4j文档

文档的某些部分需要额外维护来保持与社区同步更新。他们通常是指不同的社区贡献。下面有一个清单，正那儿你可以随时研究和检查过时的或缺少的内容！为社区做贡献的最简单方式是直接在在线HTML版本发表评论。

第 5 章 Neo4j远程客户端库

29.2.3. Neo4j的客户端驱动以及绑定

REST: 查看第 5 章 Neo4j远程客户端库获取当前活跃的社区项目。

29.3. 撰写Neo4j开发文档

注意：比起撰写文档，你也可以通过在在线HTML版本页面提交评论来帮助我们。

要获取如何编译手册，请参考：编译说明。

文档采用了asciidoc格式，请参考：

Aciidoc 参考手册

AsciiDoc 速记卡

这个速记卡真的非常棒!

29.3.1. 总体流程

每一个项目或者子项目都有它自己的文档，会生成到一个'docs.jar'文件中。默认情况下，这个文件从'src/docs/'目录的内容组装而成。 Asciidoc文档的扩展名是 .txt 。

文档可以使用来自项目的扩展代码的代码片段。相应的代码必须部署到sources.jar 或者 'test-sources.jar'文件中。

通过建立相应的单元测试，文档可以正JavaDoc备注中直接书写。

上面的文件都用来构建手册（通过增加它们作为依赖）使用。为了得到包括在手册中的内容，它必须被明确列入是手册中的文件。

注意为不同场景增加文档工作的不同方法：

为了生成详细的文档，必须把文档写来作为单元测试的一部分（包括在JavaDoc中）。在这种情况下，你一般不想在文档中链接到源代码。

为了教学级的文档，通过书写一个 .txt 的文件来包括在文本中是最好的方式。源码片段和输出范例都能从那个地方引入。在这种情况下，你一般想链接到源代码，而用户应该能不用任何额外的设置就可以运行它。

29.3.2. 在'docs.jar'中的文件结构

目录内容

dev/

面向开发人员的内容

dev/images/

面向开发人员的内容需要的图片

ops/

面向管理员的内容

ops/images/

面向管理员的内容需要的图片

man/

联机帮助页

额外子目录被用来作为文档所必须的结构，比如'dev/tutorial/'，'ops/tutorial/'等等。

29.3.3. 标题和文档结构

每一个文档都带有标题并从等级0开始。每一个文档应该有一个ID。在一些情况下，在文档中的片段也需要它们的ID，这依赖与它们是否会填充到整体结构中。为了能链接到这些内容，必须有一个ID。在强制性地方如果缺少ID在构建时将会失败。

这是一个文档的开始：

3 [[unique-id-verbose-is-ok]]

文档标题

====

为了把标题放到正确的等级下面，当在一个文件中引入另外文件时，属性 leveloffset 将会被使用。

Subsequent headings in a document should use the following syntax:

... 这是内容 ...

=== 三级标题 ===

这是内容 ...

Asciidoc对头部分的语法不止一个，但在这个项目中它不会被使用。

29.3.4. 撰写

一行写一句。这让很容易移动内容，并且很容易分拆长句。

29.3.5. 陷阱

一个章节不能是空的。 (构建时做 docbook xml合法性校验时会失败)。

文档标题应该有下划线，由与标题字符个数相同的 = 组成。

在文档末尾总是留一个空行（或者说下一个文档的标题会在文档的最后一段后结束）。

因为 {} 用来作为Asciidoc的属性，每一个内嵌正里面的都被认为是一个属性。当你必须用它的时候，请使用：+\{+。如果你不这样做，在没有任何提示或者警告的情况下，括号里面的文字会被移除。

29.3.6. 链接

为了链接到手册给定Id的其他部分，下面展示如何链接到一个参考页面：

1 <<community-docs-overall-flow>>

输出结果：第 29.3.1 节 “总体流程”

注意

只需要简单写 "看 <<target-id>>" ，在大多数情况下，这应该足够。

如果你修养链接到其他你自定义链接文本的文档，如下操作：

1 <<target-id, link text that fits in the context>>

注意

有大量的链接文本在web环境工作得很好但普通文本用于打印，而我们的目标是两个都可以。

外部链接如下：

1 http://neo4j.org/[Link text here]

输出像这样： Link text here

对于一个短地址可能不需要增加链接文本，像这样：

1 http://neo4j.org/

输出像这样： http://neo4j.org/

注意

在链接后面有一个标点符号是不受影响的，它不会被认为是链接的一部分。

29.3.7. 文本格式

_Italics_ 显示为 Italics 表示重点。

*Bold* 显示为 Bold 用来加强，仅用于加强重点。

+methodName()+ 显示为 methodName() 也被用于文字（注意：在 + 符号之间的文字会被解析）。

`command` 显示为 command (一般用于命令行)。（注意：在 ` 符号之间的文字会被解析）。

'my/path/' 显示为 my/path/ (用来表示文件名或者路径)。

``Double quoted'' (that is two grave accents to the left and two acute accents to the right) 表示为 ‘`Double quoted’'。

`Single quoted' (that is a single grave accent to the left and a single acute accent to the right) 表示为 `Single quoted'。

29.3.9. 图片

重要

正整个手册中的图片都有相同的命名空间。你指定如何管理控制它们。

图片文件

为了引入一个图片文件，确保图包括在文档目录的子目录'images/'中，然后，你可以：

1 image::neo4j-logo.png[]

输出结果：

静态的Graphviz/ DOT

我们使用Graphviz/DOT语言来描述图数据库。要获取更多的细节，请参考：http://graphviz.org/。

这是如何引入一个简单范例数据库：

4 ["dot", "community-docs-graphdb-rels.svg"]

----

"开始节点" -> "结束节点" [label="关系"]

----

输出结果：

这儿是一个在构建中使用一些预置参数的范例：

10 ["dot", "community-docs-graphdb-rels-overview.svg", "meta"]

----

"A Relationship" [fillcolor="NODEHIGHLIGHT"]

"Start node" [fillcolor="NODE2HIGHLIGHT"]

"A Relationship" -> "Start node" [label="has a"]

"A Relationship" -> "End node" [label="has a"]

"A Relationship" -> "Relationship type" [label="has a"]

Name [TEXTNODE]

"Relationship type" -> Name [label="uniquely identified by" color="EDGEHIGHLIGHT" fontcolor="EDGEHIGHLIGHT"]

----

输出结果：

传递给点过滤器的可选第二个参数定义了使用的风格：

当没定义时: 节点空间的默认样式。

neoviz: 通过Neoviz生成节点空间样式。

meta: 图数据库不会显示内容，更像是展示概念。

小心

DOT语言的关键字用于其他用途时，必须用双引号括起来。关键字包括： node， edge， graph， digraph， subgraph，和 strict.

29.3.10. 属性

你能在文档中使用的普通属性：

{neo4j-version} - 表示为 "1.8"

{neo4j-git-tag} - 表示为 "1.8"

{lucene-version} - 表示为 "3_5_0"

这些可以用来替代指向范例 APIDocs或者源代码的URL的部分。注意neo4j-git-tag也能控制snapshot/master。

能被使用的Asciidoc范例属性：

{docdir} - 指向文档的根目录

{nbsp} - 不间断空格

29.3.11. 备注

有一个独立的构件来引入备注。备注用一个黄色背景表示。默认它是不会被构建的，但在一个普通构建之后，你可以使用 make annotated 来构建它。你也能使用结果页来搜索内容，以及在一个单页面上的完整手册。

下面是范例：

1 // this is a comment

备注在一般构建结果文档中是不可见的。备注块根本不会包括在任何构建输出里面。这是一个范例：

4 ////

Note that includes in here will still be processed, but not make it into the output.

That is, missing includes here will still break the build!

////

29.3.12. 代码片段在文件中明确定义

警告

尽可能少的使用代码片段。众所周知的，它们以及很长时间没有更新了。

下面是范例：

4 [source,cypher]

----

start n=(2, 1) where (n.age < 30 and n.name = "Tobias") or not(n.name = "Tobias") return n

----

输出结果：

1 start n=(2, 1) where (n.age < 30 and n.name = "Tobias") or not(n.name = "Tobias") return n

如果没有合适的高亮语法，就省略语言设置： +[source]+。

目前下面的语言的高亮是支持的：

Bash

Cypher

Groovy

Java

JavaScript

Python

XML

更多我们能使用的高亮语言，请参考： http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/ 。

源代码中抽取

代码可以自动的从源文件中抽取。你需要定义：

component: Maven坐标的 artifactId 。

source: 指向部署的jar文件的文件路径。

classifier: sources 或者 test-sources 或者任何指向构件的分类。

tag: 用于搜索文件的tag标签。

代码语言，如果需要相应的语法高亮显示。

注意构件必须作为一个手册项目的Maven依赖被引入以便文件可以被找到。

注意标签“ABC”将匹配“ABCD”。有一个非常简单的 on/off开关，让多个出现的装配进一个单独的代码片段输出。这个行为能被用户用来当来自代码范例测试的时候隐藏断言。

这是一个定义如何包含代码片段的范例：

7 [snippet,java]

----

component=neo4j-examples

source=org/neo4j/examples/JmxTest.java

classifier=test-sources

tag=getStartTime

----

输出结果：

8 private static Date getStartTimeFromManagementBean(

GraphDatabaseService graphDbService )

{

GraphDatabaseAPI graphDb = (GraphDatabaseAPI) graphDbService;

Kernel kernel = graphDb.getSingleManagementBean( Kernel.class );

Date startTime = kernel.getKernelStartTime();

return startTime;

}

查询结果

对于Cypher查询结果有一个特殊的过滤器。这是如何标记一个查询结果：

12 .结果

[queryresult]

----

+----------------------------------+

| friend_of_friend.name | count(*) |

+----------------------------------+

| Ian | 2 |

| Derrick | 1 |

| Jill | 1 |

+----------------------------------+

3 rows, 12 ms

----

输出结果：

表 . --docbook

friend_of_friend.name count(*)

3 行, 12 毫秒

Ian

Derrick

Jill

29.3.13. 基于文档测试的一个简单Java范例

对于Java来说，有几个预置工具用来保持代码和文档都在Javadocs和代码片段中，这些代码片段生成了其它工具的的Asciidoc文档。

为了说明这个，看看下面的文档，用文件 hello-world-title.asciidoc 生成的内容是：

59 [[examples-hello-world-sample-chapter]]

Hello world 范例章节

================

这是一个范例文档测试，演示了将代码和其他构件变成Asciidoc表单的不同方法。生成文档的标题由方法名称决定，并用 " " 取代 "+_+" 。

Below you see a number of different ways to generate text from source,

inserting it into the JavaDoc documentation (really being Asciidoc markup)

via the +@@+ snippet markers and programmatic adding with runtime data

in the Java code.

- The annotated graph as http://www.graphviz.org/[GraphViz]-generated visualization:

.你好世界图

["dot", "Hello-World-Graph-hello-world-Sample-Chapter.svg", "neoviz", ""]

----

N1 [

label = "{Node\[1\]|name = \'you\'\l}"

]

N2 [

label = "{Node\[2\]|name = \'I\'\l}"

]

N2 -> N1 [

color = "#2e3436"

fontcolor = "#2e3436"

label = "know\n"

]

----

- 一个Cypher范例查询：

[source,cypher]

----

START n = node(2)

RETURN n

----

- 一个范例文本输出片段：

[source]

----

Hello graphy world!

----

- a generated source link to the original GIThub source for this test:

https://github.com/neo4j/community/blob/{neo4j-git-tag}/embedded-examples/src/test/java/org/neo4j/examples/DocumentationTest.java[DocumentationTest.java]

- The full source for this example as a source snippet, highlighted as Java code:

[snippet,java]

----

component=neo4j-examples

source=org/neo4j/examples/DocumentationTest.java

classifier=test-sources

tag=sampleDocumentation

----

以上是这个章节的全部。

这个文件通过下面的代码被引入到这个文档中：

2 :leveloffset: 3

include::{docdir}/examples/dev/examples/hello-world-sample-chapter.asciidoc[]

输出结果：

29.3.14. Hello world 范例章节

这是一个范例文档测试，演示了将代码和其他构件变成Asciidoc表单的不同方法。生成文档的标题由方法名称决定，并用 " " 取代 "_" 。

Below you see a number of different ways to generate text from source, inserting it into the JavaDoc documentation (really being Asciidoc markup) via the @@ snippet markers and programmatic adding with runtime data in the Java code.

The annotated graph as GraphViz-generated visualization:

图 29.1. 你好世界图

一个Cypher范例查询：

2 START n = node(2)

RETURN n

一个范例文本输出片段：

1 Hello graphy world!

a generated source link to the original GIThub source for this test:

DocumentationTest.java

The full source for this example as a source snippet, highlighted as Java code:

73 // START SNIPPET: _sampleDocumentation

package org.neo4j.examples;

import org.junit.Test;

import org.neo4j.kernel.impl.annotations.Documented;

import org.neo4j.test.GraphDescription.Graph;

import static org.neo4j.visualization.asciidoc.AsciidocHelper.*;

public class DocumentationTest extends AbstractJavaDocTestbase

{

/**

* This is a sample documentation test, demonstrating different ways of

* bringing code and other artifacts into Asciidoc form. The title of the

* generated document is determined from the method name, replacing "+_+" with

* " ".

* Below you see a number of different ways to generate text from source,

* inserting it into the JavaDoc documentation (really being Asciidoc markup)

* via the +@@+ snippet markers and programmatic adding with runtime data

* in the Java code.

* - The annotated graph as http://www.graphviz.org/[GraphViz]-generated visualization:

* @@graph

* - A sample Cypher query:

* @@cypher

* - A sample text output snippet:

* @@output

* - a generated source link to the original GIThub source for this test:

* @@github

* - The full source for this example as a source snippet, highlighted as Java code:

* @@sampleDocumentation

* This is the end of this chapter.

@Test

// signaling this to be a documentation test

@Documented

// the graph data setup as simple statements

@Graph( "I know you" )

// title is determined from the method name

public void hello_world_Sample_Chapter()

{

// initialize the graph with the annotation data

data.get();

gen.get().addTestSourceSnippets( this.getClass(), "sampleDocumentation" );

gen.get().addGithubTestSourceLink( "github", this.getClass(), "neo4j/community",

"embedded-examples" );

gen.get().addSnippet( "output",

createOutputSnippet( "Hello graphy world!" ) );

gen.get().addSnippet(

"graph",

createGraphVizWithNodeId( "Hello World Graph", graphdb(),

gen.get().getTitle() ) );

// A cypher snippet referring to the generated graph in the start clause

gen.get().addSnippet(

"cypher",

createCypherSnippet( "start n = node(" + data.get().get( "I" ).getId()

+ ") return n" ) );

}

// END SNIPPET: _sampleDocumentation

以上是这个章节的全部。

29.3.15. 集成远程控制台

一个交互控制台可以被新增并出现正在线HTML版本中。一个可选的标题被增加，用于按钮的文本。

这里是做法，使用Geoff来定义数据，使用空行来从查询中分割它们：

10 .与黑客帝国交互的范例

[console]

----

(A) {"name" : "Neo"};

(B) {"name" : "Trinity"};

(A)-[:LOVES]->(B)

start n = node(*)

return n

----

输出结果:

29.3.16. 工具链

当配置docbook工具链时一些有用的链接：

http://www.docbook.org/tdg/en/html/docbook.html

http://www.sagehill.net/docbookxsl/index.html

http://docbook.sourceforge.net/release/xsl/1.76.1/doc/html/index.html

http://docbook.sourceforge.net/release/xsl/1.76.1/doc/fo/index.html

第 29 章 促进 Neo4j 发展

第 29 章促进 Neo4j 发展