feat: handle documentation references both in source references and in alias catalog #2013

andsel · 2025-05-12T14:05:19Z

Closes Allow for Script documentation #174

Feature description

Implements a new DOCS directive that permit insert a link or file reference that contains the documentation for the script. The documentation reference can be also assigned to an alias of a script and in that case takes precedence over the directive present in the script.
The documentation reference can be opened with a newly added info subcommand, name docs, like:

jbang info docs <script|alias>

Describe changes at code level

The main change is to collect and resolve the reference present in the new DOCS directive in TagReader.getDocs.
During JBang project creation or update the docs reference is collected and stored, to be later read in the ScriptInfo helper class.
On the cli.Alias command a new --docs parameter is added to be accept a manually provided doc reference and store in the catalog. This catalog information is used in the ScriptInfo's initialization, after a resolution to a ResourceRef, to eventually overwrite the directive coming form the script.

How to test

Use a script like following for the testing part:

///usr/bin/env jbang "$0" "$@" ; exit $?
//DESCRIPTION This is a description test
//DOCS this_exists.txt
//DOCS ./this_exists.txt
//DOCS /tmp/this_exists.txt
//DOCS http://www.jbang.dev/documentation/guide/latest/index.html
//DOCS does-not-exist.txt

import static java.lang.System.*;

public class docsexample {

    public static void main(String... args) {
        out.println("Hello " + (args.length>0?args[0]:"World"));
    }
}

Build a new JBang distribution and and uncompress in tmp folder:

> ./gradlew distTar
> cp build/distributions/jbang-0.126.1.12.tar /tmp
> cd /tmp
> tar xf jbang-0.126.1.12.tar

In the same tmp folder create a new file this_exists.txt with some content.

Browse doc from script

/tmp/jbang-0.126.1.12/bin/jbang info docs docsexample.java

Opens a browser or an editor.

Browse doc from alias

Add an alias overriding the file's contained directive and check it opensù

/tmp/jbang-0.126.1.12/bin/jbang alias add --docs https://www.jbang.dev/documentation/guide/latest/javaversions.html docsexample.java
/tmp/jbang-0.126.1.12/bin/jbang alias list --format=json
/tmp/jbang-0.126.1.12/bin/jbang info docs docsexample

Check it opens the web browser to https://www.jbang.dev/documentation/guide/latest/javaversions.html .

Remove the alias

/tmp/jbang-0.126.1.12/bin/jbang alias remove docsexample
/tmp/jbang-0.126.1.12/bin/jbang alias list --format=json

Add an alias without a docs ref forcing

/tmp/jbang-0.126.1.12/bin/jbang alias add docsexample.java
/tmp/jbang-0.126.1.12/bin/jbang info docs docsexample

Verify if opens the editor or the browser pointing to the resource defined in the first DOCS directive

Dev tasks

complete the implementation of display the doc reference
cover with unit test
implement the catalog retrieval, giving it precedence over source file directive
check if integration tests are feasible
update the documentation

quintesse

A good first step! But there's one important change that has to be made, which is to change the type of docs from String to ResourceRef. I've left comments on the relevant sections. It makes the code slightly more complicated but it makes sure the existing machinery in JBang takes care of locating the files.

quintesse · 2025-05-15T09:22:54Z

src/main/java/dev/jbang/cli/Info.java

@@ -308,3 +317,42 @@ public Integer doCall() throws IOException {
 		return EXIT_OK;
 	}
 }
+
+@CommandLine.Command(name = "docs", description = "Open the documentation file into the default browser.")


Change "into" -> "in"

quintesse · 2025-05-15T09:25:49Z

src/main/java/dev/jbang/cli/Info.java

+	}
+
+	private static URI validateDocsReferenceAndTransformToUri(ScriptInfo info) {
+		if (info.docs.startsWith("http")) {


Once the type of info.docs is ResourceRef none if this is necessary because that type handles all of the URL vs absolute vs relative paths etc.

quintesse · 2025-05-15T09:30:42Z

src/main/java/dev/jbang/source/Project.java

@@ -37,6 +37,7 @@ public class Project {
 	private final Map<String, String> manifestAttributes = new LinkedHashMap<>();
 	private String javaVersion;
 	private String description;
+	private String docs;


The type of this shouldn't be a String but a ResourceRef

quintesse · 2025-05-15T09:32:21Z

src/main/java/dev/jbang/source/Project.java

@@ -180,6 +181,17 @@ public Project setDescription(String description) {
 		return this;
 	}

+	@Nonnull
+	public Optional<String> getDocs() {


Same here, use ResourceRef

src/main/java/dev/jbang/source/TagReader.java

src/main/java/dev/jbang/cli/Info.java

quintesse

Much better, there's still a couple of minor things and one major must fix item.

src/main/java/dev/jbang/catalog/Alias.java

src/main/java/dev/jbang/source/ProjectBuilder.java

quintesse · 2025-05-22T11:03:27Z

src/main/java/dev/jbang/source/TagReader.java

+			.findFirst();
+	}
+
+	private static ResourceRef createResourceReference(String s) {


No, this isn't how it's supposed to be done, you have to use the resolver. Like I said before, don't worry about things being downloaded, that's something we can fix later.

Honestly I don't understand. If use the resolver in thegetDoc like in the following code:

public Optional<ResourceRef> getDocs(ResourceResolver resolver) { return getTags() .filter(this::isDocsDeclare) .map(s -> s.substring(DOCS_COMMENT_PREFIX.length())) .map(resolver::resolve) .findFirst(); }

The problem I face is that when execute the jbang info docs <sometfile_with DOCS_tag>.java is that it tries to resolve. So if it point to a relative that I know exists:

[jbang] [ERROR] Could not find ./itests/this_exists.txt

or if referring to an url it tries to download the URL, while it shouldn:

[jbang] [ERROR] Could not download http://google.com

If I add the resolution I don't foresee a way to correctly execute the command.

quintesse · 2025-05-22T16:50:16Z

@andsel I updated your PR to make it work. The issue was the URL you were testing with, for now it must refer to an actual file or page

andsel · 2025-05-23T10:02:00Z

@quintesse thank's a lot for the addition, so it has to always download the url and then let it open in the browser.

I'll proceed by aligning the documentation.

quintesse · 2025-05-23T11:26:52Z

so it has to always download the url and then let it open in the browser.

No, that's just a temporary implementation detail that can be fixed later. It's of no consequence to the docs feature.

quintesse · 2025-05-23T15:40:38Z

@andsel if you rebase again against the latest version of "main" then you'll have access to lazy resource refs that I just added: #2031

You can update the code like:

prj.setDocs(tagReader.getDocs(LazyResourceResolver.lazy(resolver1)).orElse(null));

Although perhaps we can even use it for the shared resource resolver (but that would have to be thoroughly tested):

ResourceResolver resolver1 = LazyResourceResolver.lazy(new SiblingResourceResolver(resourceRef, ResourceResolver.forResources()));

andsel · 2025-05-23T15:54:08Z

@quintesse which is the best place to document this feature?

should I add a new section (like caching.adoc) to describe what's this documentation feature it?
-or- add paragraph in the "Aliases & Catalog" ? I propose this because the feature also touches the aliases creation, when a an alias can be created with a specific link to the documentation for it, which overrides the tag present in the script.

quintesse · 2025-05-23T19:09:43Z

which is the best place to document this feature?

To be honest, there currently is no "best place". We are sorely missing some organization in our docs.

should I add a new section (like caching.adoc) to describe what's this documentation feature it?

It's too small a feature IMO to merit its own page

-or- add paragraph in the "Aliases & Catalog" ? I propose this because the feature also touches the aliases creation, when a an alias can be created with a specific link to the documentation for it, which overrides the tag present in the script.

Well, then we should add all options to that page because all tags can be overridden by passing arguments to the alias. So no I don't think that's a good option either.

The real issue here is, IMO, that we're missing a page that simply shows what //-tags are available and what they are used for. Yes, a bunch of them are sprinkled throughout the docs but we're missing something that says: these are all the ones and this is what they do.

In such a page we could then show for each tag what the corresponding command line option is (eg //JAVA vs --java).
They'd also have a short description saying what each one is used for and for the ones that have additional information in other doc pages we could add links to those pages (eg, the section for //JAVA (--java) could link to https://www.jbang.dev/documentation/guide/latest/javaversions.html)

andsel · 2025-05-24T10:55:59Z

@quintesse

but that would have to be thoroughly tested
I'll rebase and test

About the documentation point:

we're missing a page that simply shows what //-tags

I've created the issue #2032 to address this (I may work on it, so eventually please assign to me)

quintesse

Almost there!

src/main/java/dev/jbang/cli/Info.java

quintesse · 2025-05-25T16:53:44Z

Btw, I'd be willing to merge this PR without the docs and leave that to be done in #2032

…ed. When the file path is relative, it tries to use project mainSource, or if not available consider current working dir.

…or the alias

…e catalog (if present)

…project

…ence, if present

… builder during project creation

quintesse

LGTM

andsel · 2025-05-29T07:34:24Z

@quintesse thanks a lot for your all your guidance on this! :-D

quintesse · 2025-05-29T09:46:17Z

@quintesse thanks a lot for your all your guidance on this! :-D

And thank you for your implementation and in moving this issue forward! :-)

andsel changed the title ~~[WIP] Process and manage DOCS tag feature~~ feat: handle documentation references both in source references and in alias catalog May 14, 2025

andsel force-pushed the feature/add_docs_tag branch 4 times, most recently from e4220d3 to c0ae56a Compare May 15, 2025 00:04

quintesse requested changes May 15, 2025

View reviewed changes

quintesse requested changes May 22, 2025

View reviewed changes

quintesse force-pushed the feature/add_docs_tag branch from bffa14b to 4d5c656 Compare May 22, 2025 17:02

andsel force-pushed the feature/add_docs_tag branch from 4d5c656 to 7255f14 Compare May 23, 2025 10:23

andsel mentioned this pull request May 24, 2025

[Docs] Create summary page for directives #2032

Open

andsel marked this pull request as ready for review May 25, 2025 10:24

andsel marked this pull request as draft May 25, 2025 10:25

andsel force-pushed the feature/add_docs_tag branch 2 times, most recently from 04944c1 to 760deb7 Compare May 25, 2025 16:08

quintesse requested changes May 25, 2025

View reviewed changes

src/main/java/dev/jbang/cli/Info.java Outdated Show resolved Hide resolved

andsel added 7 commits May 28, 2025 22:33

Added docs tag to parser and managed to open the url or file referenc…

dd1b63e

…ed. When the file path is relative, it tries to use project mainSource, or if not available consider current working dir.

Add --docs switch to alias add to store the documentation reference f…

543cd27

…or the alias

Updaated alias list to show also the docs-ref attributes stored in th…

82f9a35

…e catalog (if present)

Fixed test syntax failed, Alias requires docs-ref

7199b65

Added null check on prj.mainSource while retrieving root dir for the …

32d8ea2

…project

Fixed formatting with a spotless step

e626031

Moved docs reference frpom String type to ResourceRef

bd3d332

andsel and others added 7 commits May 28, 2025 22:33

Rename docs-ref to docs

6474e73

Made docs resolving work

5bab9a2

Added some tests

afb7b7b

Used the new lazy resolver

d8d18db

Modified subcommand to give precedence on alias's documentation refer…

6f1f628

…ence, if present

Moved resolution of docs directive vs alias provided into the project…

81132a1

… builder during project creation

chore: rewrote docs handling in ProjectBuilder a bit

7984ce5

quintesse force-pushed the feature/add_docs_tag branch from 0c5a911 to 7984ce5 Compare May 28, 2025 20:33

quintesse self-requested a review May 28, 2025 20:33

chore: minor code cleanup

538b650

quintesse force-pushed the feature/add_docs_tag branch from cac4902 to 538b650 Compare May 28, 2025 20:39

quintesse approved these changes May 28, 2025

View reviewed changes

andsel marked this pull request as ready for review May 29, 2025 06:48

feat: handle documentation references both in source references and in alias catalog #2013

Are you sure you want to change the base?

feat: handle documentation references both in source references and in alias catalog #2013

Uh oh!

Conversation

andsel commented May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Feature description

Describe changes at code level

How to test

Browse doc from script

Browse doc from alias

Dev tasks

Uh oh!

quintesse left a comment

Choose a reason for hiding this comment

Uh oh!

quintesse May 15, 2025

Choose a reason for hiding this comment

Uh oh!

quintesse May 15, 2025

Choose a reason for hiding this comment

Uh oh!

quintesse May 15, 2025

Choose a reason for hiding this comment

Uh oh!

quintesse May 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

quintesse left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

quintesse May 22, 2025

Choose a reason for hiding this comment

Uh oh!

andsel May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quintesse commented May 22, 2025

Uh oh!

andsel commented May 23, 2025

Uh oh!

quintesse commented May 23, 2025

Uh oh!

quintesse commented May 23, 2025

Uh oh!

andsel commented May 23, 2025

Uh oh!

quintesse commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andsel commented May 24, 2025

Uh oh!

quintesse left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

quintesse commented May 25, 2025

Uh oh!

quintesse left a comment

Choose a reason for hiding this comment

Uh oh!

andsel commented May 29, 2025

Uh oh!

quintesse commented May 29, 2025

Uh oh!

Uh oh!

andsel commented May 12, 2025 •

edited

Loading

andsel May 22, 2025 •

edited

Loading

quintesse commented May 23, 2025 •

edited

Loading