You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.asciidoc
-74
Original file line number
Diff line number
Diff line change
@@ -5,77 +5,3 @@ This repository contains tools and tests for proving and generating documentatio
5
5
All docs sources are maintained in AsciiDoc format.
6
6
The primary output of building the projects kept here are artifacts (JARs) containing docs sources, code examples, and some scripts and images.
7
7
These are processed downstream with custom tools, Asciidoctor and XSLT to produce the library of documentation available at https://neo4j.com/docs/.
8
-
9
-
10
-
== Building
11
-
12
-
Running `mvn clean install` will build and install all artifacts.
13
-
Modules that test or generate documentation as part of their build will produce a `-docs.jar` artifact.
14
-
The `contents` module collects these into a `neo4j-manual-contents` jar.
15
-
Beyond this überJAR the `javadocs` and `cypher/refcard-tests` modules also produce special-purpose content JARs.
16
-
17
-
The tools and tests run against Neo4j product artifacts.
18
-
These can be downloaded from Maven Central, as ordinary dependencies.
19
-
It is also possible to build Neo4j locally, and either deploy to a flatfile `-DaltDeploymentRepository` or install in the local Maven cache.
20
-
The tools and tests in this repository can then be built and run against the locally produced Neo4j artifacts.
21
-
This is the workflow for building Neo4j documentation while developing Neo4j the product.
22
-
23
-
24
-
== Local pipeline
25
-
26
-
The easiest way to build Neo4j and Neo4j documentation in step is to rely on the local Maven cache.
27
-
Running `mvn clean install -DskipTests -T1.5C` in your local Neo4j clone followed by `mvn clean install` in your clone of this repository will achieve this.
28
-
This is not very robust, however.
29
-
Pretty soon Neo4j artifacts will be published to the Neo4j snapshot repository that are newer than the ones you have installed locally, and your docs build will start pulling these in instead.
30
-
It is also very difficult to know which artifacts are actually being used.
31
-
A module or part of a module depended on in the docs build may even be removed from the product without this surfacing and the build breaking.
32
-
As long as you have some `SNAPSHOT` artifact for the correct version installed in the local cache this will continue to be used, until a release happens and the version is bumped.
33
-
34
-
The less easy but more robust way to develop Neo4j and dependents like documentation in step, is to emulate a CI release pipeline locally.
35
-
This could involve things like setting an explicit version on the artifacts produced, and not rely on the ever-fleeting Maven `SNAPSHOT`.
36
-
To control the dependency chain, and to avoid interfering with other builds that may share dependencies, it may be a good idea to deploy or install artifacts in custom locations.
37
-
The `in/` and `out/` for each build in the pipeline can be configured to provide the desired insulation.
As commandline interaction this may seem a bit heavy-handed.
65
-
One might then consider separating _configuration_ (environment variables, symlinks, etc.) into a developer-common `devenv` and a developer-local `devenv.local` file to be sourced, and _commands_ (Maven invocations) into a `run-build` script to be executed.
66
-
An interaction cycle might then be:
67
-
68
-
.Build Neo4j and Neo4j Documentation
69
-
[source, sh]
70
-
----
71
-
$ cd $MY_NEO4J_CLONE
72
-
$ . ./devenv # which in turn sources ./devenv.local
73
-
$ ./run-build
74
-
$ cd $MY_NEO4J_DOCUMENTATION_CLONE
75
-
$ . ./devenv
76
-
$ ./run-build
77
-
----
78
-
79
-
This interaction might in turn easily be automated by either running one build and listen for changes to trigger others, or by scripting the steps for manual execution.
80
-
Sprinkle some git commit hooks on top _et voilà_, you are now Snapping the CI on your own developer box.
0 commit comments