Asciidoctor :: Discussion

antora referencing source beneath src folder

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

ante

Apr 24, 2020; 11:48am

antora referencing source beneath src folder

5 posts

This post was updated on Apr 24, 2020; 1:05pm.

hi all,

i managed to convince my teammembers to use asciidoc + antora and we set it up and it is running fine.
but i wonder how to organize my dirs and files when i want to reference (include:link) code the antora way when it is not located within the antora related content tree, i.e. the actual source of a component

current file structure

component
|_ docs/...
| |_ antora.yml
| |_ module-x
| |_ pages
| | |_ about_modules.adoc
| |_ examples
| |_ copy_some_module.py
|_ src
|_ module-x
|_ some_module.py

while I know that referencing some_module.py with include::<module-name>:some_module.py[tag=...] with that structure will not work, i can only copy it to examples folder in order to include it the antora way...

i am not sure, but i think i found once a dicsussion on that, but cannot find it anymore...
so do you have ideas on how to handle source content in folder-foreign locations like that or
is it just not meant to be used that way?

thanks for reply!

David Jencks

Apr 24, 2020; 2:37pm

Re: antora referencing source beneath src folder

68 posts

Right now in Antora included content has to be in the antora structure.

There’s some more flexibility available than you may be aware of through using distributed components, where you can have several antora structured source trees contributing to the same component/version, either in different repos or the same repo at multiple start paths. I think the documentation for this has been updated extensively recently.

There are two directions of extension being considered, probably for Antora 3:

- adding sources to the Antora content catalog from non-default locations. Such a location could be an alternate path in an already-known git repo, or an external source such as a javadoc jar. (those are two choices I’ve prototyped). After the content gets catalogued, you refer to it using an antora resource id.

- remote includes, where an include:: points to a URL not in a known git repo.

In the projects I’m aware of with this problem right now, which are large java projects that need to transfer content from a maven-based build location associated with the java source to an antora structure, there are build scripts that copy the source into the antora structure, where it’s checked in to git.

Hope this helps,

David Jencks

On Apr 24, 2020, at 4:48 AM, ante [via Asciidoctor :: Discussion] <[hidden email]> wrote:

hi all,

i managed to convince my teammembers to use asciidoc + antora and we set it up and it is running fine.
but i wonder how to organize my dirs and files when i want to reference (include:link) code the antora way when it is not located within the antora related content tree, i.e. the actual source of a component

or is it bad practice to do it like that and should i only use code transferred to module/<module-name>/examples?
i am not sure, but i think i found once a dicsussion on that but cannot find it anymore...

does anybody have an advice on that?

thanks for reply!

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/antora-referencing-source-beneath-src-folder-tp7953.html

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

... [show rest of quote]

mojavelinux

Apr 24, 2020; 9:24pm

Re: antora referencing source beneath src folder

Administrator

2681 posts

In reply to this post by ante

> but i wonder how to organize my dirs and files when i want to reference (include:link) code the antora way when it is not located within the antora related content tree, i.e. the actual source of a component

This is not currently possible in Antora (by default). Refer to the following open issue: https://gitlab.com/antora/antora/-/issues/195

There are two ways around it that I can suggest:

* Move those files you want to include into the Antora content hierarchy

* Use a custom site generator component to import additional files in the Antora content catalog after it retrieves the files from the git indexes / worktrees

If you have a situation where an include doesn't resolve when you're not using Antora, you can register an include processor that emulates the behavior of Antora's include processor.

Best Regards,

-Dan

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

ante

Apr 27, 2020; 8:43am

Re: antora referencing source beneath src folder

5 posts

In reply to this post by David Jencks

Hi David,

thanks for reply.

ok, the copy option like Dan also suggested is a valid point.
i already thought about it, but in the same time it feels to me like to be against DRY concept.
But anyway this is just my affectivity :)

Best wishes
Ante

ante

Apr 27, 2020; 8:47am

Re: antora referencing source beneath src folder

5 posts

In reply to this post by mojavelinux

Hi Dan,

thx as well for your answer

the release for V3 looks promising :)

thow one question to that for i eventually missed it in the list, will asciidoctor 2.x also be integrated?

Best wishes
Ante

mojavelinux

Apr 27, 2020; 10:28am

Re: antora referencing source beneath src folder

Administrator

2681 posts

Yes, that's the first change that will be made.

-Dan

On Mon, Apr 27, 2020 at 2:47 AM ante [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi Dan,

thx as well for your answer

the release for V3 looks promising :)

thow one question to that for i eventually missed it in the list, will asciidoctor 2.x also be integrated?

Best wishes
Ante

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/antora-referencing-source-beneath-src-folder-tp7953p7959.html

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

... [show rest of quote]

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux