Neo4j uses asciidoc

538 views
Skip to first unread message

Anders Nawroth

unread,
Mar 30, 2011, 8:10:03 AM3/30/11
to asci...@googlegroups.com
Hi!

The Neo4j graph database project uses Asciidoc, and the output is
published here:
http://docs.neo4j.org/

The build process is rather complex, with the master documents and
configuration stored here:
https://github.com/neo4j/server/tree/master/manual

We also have our own filter to include code snippets:
https://github.com/neo4j/server/tree/master/manual/src/bin/resources/snippet
The syntax we use may look strange, but it's very readable. The filter
is tailored for our build setup, but it shouldn't be hard to change it
to fit other cases.

We want to keep documentation and code close to each other, so each
project has it's own documents, and that gets pulled together by the
Maven build tool and pushed onto some scripting that executes asciidoc/a2x.

So for example the code snippets on this page:
http://docs.neo4j.org/chunked/snapshot/indexing-create.html
are included from this document:
https://github.com/neo4j/graphdb/blob/master/lucene-index/src/docs/dev/index.txt#L32
The code included lives here:
https://github.com/neo4j/graphdb/blob/master/lucene-index/src/test/java/examples/ImdbExampleTest.java
and is tested on each commit.

I just thought this could be interesting to someone on this list :-) And
of course for the list of projects using Asciidoc!

BTW, we're still on version 8.6.3 - I hope to upgrade in a couple of
weeks. So I haven't looked into how filters are handled in 8.6.4 yet.

/anders

Stuart Rackham

unread,
Apr 11, 2011, 2:29:31 AM4/11/11
to asci...@googlegroups.com
Hi Anders

On 31/03/11 01:10, Anders Nawroth wrote:
> Hi!
>
> The Neo4j graph database project uses Asciidoc, and the output is published here:
> http://docs.neo4j.org/
>
> The build process is rather complex, with the master documents and configuration
> stored here:
> https://github.com/neo4j/server/tree/master/manual

Very impressive, it amazes me what people get up to with AsciiDoc.


>
> We also have our own filter to include code snippets:
> https://github.com/neo4j/server/tree/master/manual/src/bin/resources/snippet
> The syntax we use may look strange, but it's very readable. The filter is
> tailored for our build setup, but it shouldn't be hard to change it to fit other
> cases.

It's a nice solution to your snippet problem, can it be installed using the new
Filter Plugins mechanism (http://www.methods.co.nz/asciidoc/filters.html)? I'm
certain that a lot of other users would be interested in using it.


>
> We want to keep documentation and code close to each other, so each project has
> it's own documents, and that gets pulled together by the Maven build tool and
> pushed onto some scripting that executes asciidoc/a2x.
>
> So for example the code snippets on this page:
> http://docs.neo4j.org/chunked/snapshot/indexing-create.html
> are included from this document:
> https://github.com/neo4j/graphdb/blob/master/lucene-index/src/docs/dev/index.txt#L32
>
> The code included lives here:
> https://github.com/neo4j/graphdb/blob/master/lucene-index/src/test/java/examples/ImdbExampleTest.java
>
> and is tested on each commit.
>
> I just thought this could be interesting to someone on this list :-) And of
> course for the list of projects using Asciidoc!

I've added it the list on the AsciiDoc home page -- let me know if it needs editing.

>
> BTW, we're still on version 8.6.3 - I hope to upgrade in a couple of weeks. So I
> haven't looked into how filters are handled in 8.6.4 yet.

Probably answers my Filter Plugins question.

Cheers, Stuart

>
> /anders
>

Anders Nawroth

unread,
Apr 13, 2011, 8:21:17 AM4/13/11
to asci...@googlegroups.com
Hi!

On 04/11/2011 08:29 AM, Stuart Rackham wrote:
> Hi Anders
>
> On 31/03/11 01:10, Anders Nawroth wrote:
>> Hi!
>>
>> The Neo4j graph database project uses Asciidoc, and the output is
>> published here:
>> http://docs.neo4j.org/
>>
>> The build process is rather complex, with the master documents and
>> configuration
>> stored here:
>> https://github.com/neo4j/server/tree/master/manual
>
> Very impressive, it amazes me what people get up to with AsciiDoc.

Well, I'm amazed by AsciiDoc :-) It handles a lot of use cases well, and
some other cases are still possible at least.

>> We also have our own filter to include code snippets:
>> https://github.com/neo4j/server/tree/master/manual/src/bin/resources/snippet
>>
>> The syntax we use may look strange, but it's very readable. The filter is
>> tailored for our build setup, but it shouldn't be hard to change it to
>> fit other
>> cases.
>
> It's a nice solution to your snippet problem, can it be installed using
> the new Filter Plugins mechanism
> (http://www.methods.co.nz/asciidoc/filters.html)? I'm certain that a lot
> of other users would be interested in using it.

At the moment we're under too heavy load to fix this (and even to
upgrade to the new AsciiDoc version) but maybe we'll get around doing
that eventually. Inbetween the code is open source so anyone who's more
into the details regarding AsciiDoc can have a look at it :-)

> I've added it the list on the AsciiDoc home page -- let me know if it
> needs editing.

Looks perfect to me.

>>
>> BTW, we're still on version 8.6.3 - I hope to upgrade in a couple of
>> weeks. So I
>> haven't looked into how filters are handled in 8.6.4 yet.
>
> Probably answers my Filter Plugins question.

Exactly.


/anders

>
> Cheers, Stuart
>
>>
>> /anders
>>
>

Reply all
Reply to author
Forward
0 new messages