Asciidoctor :: Discussion

asciidoctor-j based documentation generator

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

10 messages Options

PzdcDoc

May 04, 2019; 8:35pm

asciidoctor-j based documentation generator

Hi all,

first of all thanks a lot for doing of this great product.
AsciiDoctor gave us so needed standardizing and flexibility and I found it the best currently existing solution for making software documentation.
However there were some missing things from my perspective:
- orientation on large *.adoc files;
- no recommended structure for storing resources;
- references checking;
- search in created documentation using JS.

I know, that partially it might be solved using converting to DocBook format first.
But we went our way, and short time ago our solution was published here: https://github.com/pzdcdoc/pzdcdoc

So it has to be some restricted and maximally simplified way of building documentation.
I kindly ask everybody here about feedback:
- is such thing needed for somebody else;
- does it make sense to keep it separately or better try to integrate in one of existing projects.

Thanks.

abelsromero

May 05, 2019; 8:32am

Re: asciidoctor-j based documentation generator

Welcome to the forums and thx for the encouraging words.

There are several tools to build documentation that sit on top of asciidoctor and that depends on your the use case.
If you need to build documentation sites I'd strongly recommend antora (https://antora.org/), its own document is written with it so you can see how the defaults look (https://docs.antora.org).
Antora checks out-of-the-box all your points except for "search in created documentation using JS" for which there are third party options.

Note it uses asciidoctor.js under the hood, not AsciidoctorJ. Don't be afraid if your are not familiar with JS tools, features are 100% the same and at the end of the day once installed (with npm or just use docker) you use it as any other cli command.

abelsromero

May 05, 2019; 8:34am

Re: asciidoctor-j based documentation generator

Just saw the issue in Github and saw that I just game a similar answer

. I assure it was just coincidence.

PzdcDoc

May 05, 2019; 8:59am

Re: asciidoctor-j based documentation generator

Thanks for the response.

Yes, Antora seems to be quite similar. Didn't notice it before. I will have a closer look.
And there is embedded search already at docs.antora.org, isn't it available out of box?

Which other tool did you mention?

Java is preferable way for me, bacause of using it in most of projects..
So ideally it has to be one artifact in Maven Central with main class.
I know, what NodeJS is nearly the same, it is only question of already using stack and getting new dependencies.

PzdcDoc

May 05, 2019; 9:16am

Re: asciidoctor-j based documentation generator

In reply to this post by abelsromero

What I also missed in Antora: Preview at GitLab/GitHub, because of using separated .yml configurations and custom constructions instead of simple references.

mojavelinux

May 05, 2019; 9:31am

Re: asciidoctor-j based documentation generator

Administrator

Simple references are only going to get you so far. In Antora, we made the tough but important choice not to be constrained by what GitHub allows and instead develop a robust and comprehensive referencing system that enables you to create the types of references that enterprise documentation requires. It's a trade-off for sure, but we believe one that will pay off in the long run. (And there's always a chance that GitHub will catch up).

In other words, we're not going to allow GitHub to dictate the type of references that we're allowed to make. It's simply too limiting. In the end, perfect GitHub preview just isn't that important, esp since the site is being continuously published in full fidelity (theme and all).

Best,

-Dan

On Sun, May 5, 2019 at 3:16 AM PzdcDoc [via Asciidoctor :: Discussion] <[hidden email]> wrote:

What I also missed in Antora: preview on GitLab/GitHub, because of using separated .yml configurations and custom constructions instead of simple references.

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/asciidoctor-j-based-documentation-generator-tp6888p6892.html

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

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

abelsromero

May 05, 2019; 9:37am

Re: asciidoctor-j based documentation generator

In reply to this post by PzdcDoc

PzdcDoc wrote

Yes, Antora seems to be quite similar. Didn't notice it before. I will have a closer look.
And there is embedded search already at docs.antora.org, isn't it available out of box?

Antora uses angolia (https://www.algolia.com/) for the content indexation and search box in the docs site.
Afaik it offers some free options for open source projects. Other than that I googled some time ago and found some JS libs but I am not sure how good they are.

PzdcDoc wrote

Java is preferable way for me, bacause of using it in most of projects..
So ideally it has to be one artifact in Maven Central with main class.
I know, what NodeJS is nearly the same, it is only question of already using stack and getting new dependencies.

Antora runs on JS, so there's no Java alternative. However, don't be afraid, I come from the same place and I can assure there's nothing to worry. All the team at the office is happy with it and we are all Java devs.
To simplify installation, just use docker if you don't want to "pollute" your machine with npm home directory https://docs.antora.org/antora/2.0/antora-container/. If you're prefer to install antora on bare metal, just use "nvm", it's available for Windows and Linux. https://docs.antora.org/antora/2.0/install/linux-requirements/
If it helps, on Windows I use the Linux tools in a WSL machine.

mojavelinux

May 05, 2019; 9:55am

Re: asciidoctor-j based documentation generator

Administrator

> Antora uses angolia (https://www.algolia.com/) for the content indexation and search box in the docs site.

Technically, Antora doesn't use anything. It's up to you what you want to use. Algolia docsearch happens to work well because you simply point it at a site and it gives you an index that you can query via JavaScript.

For more details of this discussion, see:

* https://gitlab.com/antora/antora-ui-default/issues/68

* https://gitlab.com/antora/antora-ui-default/issues/44

> Antora runs on JS, so there's no Java alternative.

While that's true, it's possible to run JavaScript / Node applications via Gradle. Schalk has been working on Asciidoctor.js integration in the Asciidoctor Gradle plugin, and I suspect that Antora integration isn't that far off.

Best,

-Dan

On Sun, May 5, 2019 at 3:37 AM abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

PzdcDoc wrote

Yes, Antora seems to be quite similar. Didn't notice it before. I will have a closer look.
And there is embedded search already at docs.antora.org, isn't it available out of box?

Antora uses angolia (https://www.algolia.com/) for the content indexation and search box in the docs site.
Afaik it offers some free options for open source projects. Other than that I googled some time ago and found some JS libs but I am not sure how good they are.

PzdcDoc wrote

Java is preferable way for me, bacause of using it in most of projects..
So ideally it has to be one artifact in Maven Central with main class.
I know, what NodeJS is nearly the same, it is only question of already using stack and getting new dependencies.

Antora runs on JS, so there's no Java alternative. However, don't be afraid, I come from the same place and I can assure there's nothing to worry. All the team at the office is happy with it and we are all Java devs.
To simplify installation, just use docker if you don't want to "pollute" your machine with npm home directory https://docs.antora.org/antora/2.0/antora-container/. If you're prefer to install antora on bare metal, just use "nvm", it's available for Windows and Linux. https://docs.antora.org/antora/2.0/install/linux-requirements/
If it helps, on Windows I use the Linux tools in a WSL machine.

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/asciidoctor-j-based-documentation-generator-tp6888p6894.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

PzdcDoc

May 05, 2019; 10:48am

Re: asciidoctor-j based documentation generator

In reply to this post by abelsromero

abelsromero wrote

Antora runs on JS, so there's no Java alternative. However, don't be afraid, I come from the same place and I can assure there's nothing to worry. All the team at the office is happy with it and we are all Java devs.
To simplify installation, just use docker if you don't want to "pollute" your machine with npm home directory https://docs.antora.org/antora/2.0/antora-container/. If you're prefer to install antora on bare metal, just use "nvm", it's available for Windows and Linux. https://docs.antora.org/antora/2.0/install/linux-requirements/
If it helps, on Windows I use the Linux tools in a WSL machine.

It is not about being afraid. I know NodeJS and am able to use it..
Unfortunately there is no way in modern world to avoid JS

But about maximum simplification of environment configuration for each of developers.
Right now for building of our project is enough to have installed JDK8 and we try to stick on it.
Installing two or more additional stuff on any of developers systems is too time consuming.
Even Docker may do not exist there.

Of course, it is matter of taste. And it is the good thing in Open Source, that anyone can choice.
For us right now three small additional Java classes on top of asciidoctor-j is the best option.
Will see, when nobody else need that - they will just live further in out Utils.
Or maybe we will switch to Antora, I haven't analyzed it yet deep enough.

mojavelinux

May 05, 2019; 10:51am

Re: asciidoctor-j based documentation generator

Administrator

> And it is the good thing in Open Source, that anyone can choice.

For us right now three small additional Java classes on top of asciidoctor-j is the best option.

100% While we provide suggestions here, they are just that, suggestions. The Asciidoctor ecosystem is vast and those options are a great thing. Find what works best for you.

Best,

-Dan

On Sun, May 5, 2019 at 4:48 AM PzdcDoc [via Asciidoctor :: Discussion] <[hidden email]> wrote:

abelsromero wrote

Antora runs on JS, so there's no Java alternative. However, don't be afraid, I come from the same place and I can assure there's nothing to worry. All the team at the office is happy with it and we are all Java devs.
To simplify installation, just use docker if you don't want to "pollute" your machine with npm home directory https://docs.antora.org/antora/2.0/antora-container/. If you're prefer to install antora on bare metal, just use "nvm", it's available for Windows and Linux. https://docs.antora.org/antora/2.0/install/linux-requirements/
If it helps, on Windows I use the Linux tools in a WSL machine.

It is not about being afraid. I know NodeJS and am able to use it..
Unfortunately there is no way in modern world to avoid JS
But about maximum simplification of environment configuration for each of developers.
Right now for building of our project is enough to have installed JDK8 and we try to stick on it.
Installing two or more additional stuff on any of developers systems is too time consuming.
Even Docker may do not exist there.

Of course, it is matter of taste. And it is the good thing in Open Source, that anyone can choice.
For us right now three small additional Java classes on top of asciidoctor-j is the best option.
Will see, when nobody else need that - they will just live further in out Utils.
Or maybe we will switch to Antora, I haven't analyzed it yet deep enough.

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/asciidoctor-j-based-documentation-generator-tp6888p6896.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