Great insights Anders!

There's no question that tackling this challenge requires more experimentation. And it's still a problem we need to solve to get the documentation for the Asciidoctor family of projects streamlined on asciidoctor.org (right now we're manually copying README files, which is about as far from ideal as you can get). (see https://github.com/asciidoctor/asciidoctor.org/issues/366)

Using a dependency management system is certainly an excellent way to specify and manage the relationships. You build on top of a mature model that already handles concerns like artifact resolution, versioning and resource loading.

For me, the (only) drawback of the setup Anders outlines is that it relies heavily on the build, making it a more formal process. In an ideal world, it should be possible to preview the documents with or without the build (casually)...but that requires a lot more thought and planning to setup (and some AsciiDoc tricks). 

Gradle's continuous build mode does have the potential to address this drawback because you can start the build (much like a server) and just keep it running. As a result, you see changes instantaneously in the output files when you make a change to a source file. But that setup may still break the ability to use an editor like Atom or Brackets to preview the documents in their original form. So I'll finish with...

More research is needed in this area :)

-Dan

On Fri, Sep 25, 2015 at 6:24 PM, nawroth [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi Michael!

I have every module provide a [modulename]-[version]-docs.jar, just
like normal jars (or sources or test-sources or javadoc jars common in
Java land).
The main documentation build unpacks those jars, and then all of the
documentation is built in one go.

It's quite easy to do this using Maven. For extra convience and some
additional magic, I built a Maven plugin for creating the docs jars.
I wouldn't be surprised if it's even easier using Gradle (we're
considering switching).

One nice feature of using dependency management is that modules can be
moved around without breaking anything.

Here's an outdated writeup of what we're doing:
http://neo4j.com/docs/2.2.5/community-docs.html

The tricky part over time, as the number of modules grow, is to find
the best location for all parts of the documentation.

Feel free to ask any questions you have about our setup!

/anders

2015-09-23 19:24 GMT+02:00 Michael_M [via Asciidoctor :: Discussion]
<[hidden email]>:

> I'm trying to figure out the best way to include documentation from other
> (independent) modules. I'm hoping that someone has done this before and can
> share some pointers.
>
> Let's assume that my project P depends on modules A and B. There are 3 Git
> repositories: P, A and B each reside in their own Git repository containing
> the source code and the documentation.
>
> Just as in the code, the dependencies  are specific to a particular version.
> So I want all include:: directives that point to A, to point to a specific
> git branch of A.
>
> There are 2 approaches I am considering:
> 1. Use attributes in the asciidoc document in P, and point to the specific
> version.
> E.g:
> :repo_a: https://raw.githubusercontent.com/username/project_A/v3.5
>
> My concern with this approach: what happens with the includes directives in
> A? And images?
>
> Approach 2: Use Gradle to handle the dependencies. I assume that Gradle
> would have to download the correct branch of A and B. I'm not sure how this
> could be setup with directory structures.
>
> Any thoughts?
>
> ________________________________
> If you reply to this email, your message will be added to the discussion
> below:
> http://discuss.asciidoctor.org/Asciidoc-and-dependency-management-tp3751.html
> To start a new topic under Asciidoctor :: Discussion, email

> [hidden email]
> To unsubscribe from Asciidoctor :: Discussion, click here.
> NAML

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Asciidoc-and-dependency-management-tp3751p3755.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen