Catalog documentation page generation

[nandorholozsnyak]

Is your feature request related to a problem? Please describe.
It is not a problem in my opinion, an idea, addition to the JBang toolset.

Describe the solution you'd like
On the web I saw a few jbang-catalog GitHub repositores, but none of them had a typical well formatted README.MD where you could see all the available aliases and/or templates. Of course there are a few one, that has proper documentation, but most of them are empty. I think JBang should provide a way where you can generate a documentation that describes the content of your jbang-catalog.json file in your repository. In my opinion it can be a simple Markdown file or an AsciiDoc as well. If you would like to host it as a GitHub page, then an HTML could work as well.

On my fork I created a new subcommand for the catalog command that is named documentation and it can be used to generate a markdown file that contains everything from the jbang-catalog.json that could be used with a flag.

So for example if I run the command jbang catalog documentation -f jbang-catalog/jbang-catalog.json -O catalog-test.md against this file (https://github.com/nandorholozsnyak/jbang-catalog/blob/feature/aws-lambda-templates/jbang-catalog.json) on my local machine, then the following output will be generated:

Catalogs

Aliases

buginfo

Usage: jbang buginfo [args...]

Script reference: quarkusissue.java

---

catalog_check_updates

Usage: jbang catalog_check_updates [args...]

Script reference: catalog_check_updates.java

---

catalog_publish

Usage: jbang catalog_publish [args...]

Script reference: catalog_publish.java

---

cli

Usage: jbang cli [args...]

Script reference: https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/2.6.1.Final/quarkus-cli-2.6.1.Final-runner.jar

---

qs

Usage: jbang qs [args...]

Script reference: https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/2.6.1.Final/quarkus-cli-2.6.1.Final-runner.jar

---

quarkus

Usage: jbang quarkus [args...]

Script reference: https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/2.6.1.Final/quarkus-cli-2.6.1.Final-runner.jar

---

Templates

githubbot

Usage: jbang init -t=githubbot script.java [args...]

File references:

• {basename}.java - qbot/bot.java.qute
• bot-index.html - qbot/bot-index.html
• .env - qbot/.env
• qbot.png - qbot/qbot.png
• readme.adoc - qbot/readme.adoc.qute

---

q-aws-lambda

Usage: jbang init -t=q-aws-lambda script.java [args...]

File references:

• {filename} - aws/aws-lambda.java.qute
• application.properties - aws/application.properties

---

q-aws-lambda-tf

Usage: jbang init -t=q-aws-lambda-tf script.java [args...]

File references:

• {filename} - aws/aws-lambda.java.qute
• generate-jar.sh - aws/generate-jar.sh
• generate-native-image.sh - aws/generate-native-image.sh
• application.properties - aws/application.properties
• lambda-aws.tf - aws/lambda-aws.tf.qute

---

q-aws-lambda-funq

Usage: jbang init -t=q-aws-lambda-funq script.java [args...]

File references:

• {filename} - aws/aws-lambda-funq.java.qute
• application.properties - aws/application.properties

---

q-aws-lambda-funq-tf

Usage: jbang init -t=q-aws-lambda-funq-tf script.java [args...]

File references:

• {filename} - aws/aws-lambda-funq.java.qute
• application.properties - aws/application.properties
• lambda-funq.tf - aws/lambda-funq.tf.qute

---

q-aws-lambda-sqs

Usage: jbang init -t=q-aws-lambda-sqs script.java [args...]

File references:

• {filename} - aws/aws-lambda-sqs.java.qute
• application.properties - aws/application.properties

---

q-aws-lambda-sqs-funq

Usage: jbang init -t=q-aws-lambda-sqs-funq script.java [args...]

File references:

• {filename} - aws/aws-lambda-sqs-funq.java.qute
• application.properties - aws/application.properties

---

q-aws-lambda-s3

Usage: jbang init -t=q-aws-lambda-s3 script.java [args...]

File references:

• {filename} - aws/aws-lambda-s3.java.qute
• application.properties - aws/application.properties

---

q-aws-lambda-s3-funq

Usage: jbang init -t=q-aws-lambda-s3-funq script.java [args...]

File references:

• {filename} - aws/aws-lambda-s3-funq.java.qute
• application.properties - aws/application.properties

---

The command can take the following parameters:

• --output -O - where the file should be rendered and named, by default catalog.md
• --template -T - the template that should be used during the render process, by default catalog.md.qute
• --catalog-logo -cl - the logo that will be rendered into the final document, by default JBang logo.

The template right now is using the internal implementation of the dev.jbang.catalog.Catalog class (like catalogs, aliases, templates) - I can imagine on the long run to map it to some other models.

My initial implementation does only the basics, I can imagine that it would include a header and a footer section, but I'm curious if it could be used as an "official" JBang catalog documentation generator, to make sure that your GitHub repository is shiny and "standardízed" if it a real JBang catalog repository.

Initial implementation can be found in this commit: nandorholozsnyak@2241bf4

[quintesse]

I definitely like what you did, but I wonder if this should be part of the core jbang functionality or is exactly the kind of thing that could be an external/3rd party script that people can use.

It could also be a plugin (if/when that functionality gets merged: #1000)

(Personally I already feel that Jbang is getting "fat" and we could look at moving more things to plugins 😉 )

[maxandersen]

Awesome idea and I thought about the same. I do think this is better done by a external script - possibly hosted on jbangdev catalog.

I actually wondered if should make jbang.dev/AppStore have subpages for each catalog found.

Could have your script run on every found catalog and update the AppStore.

[nandorholozsnyak]

Thank you guys, then I will fork the jbangdev catalog make open a PR there when I finish it.
I will try to make sure it is as customizable as possible.
Should we close the ticket?

[quintesse]

Probably yes. Just open a new issue in the catalog repo with a link to this one.

[nandorholozsnyak]

Okay cool. Will do, thanks @quintesse .

[nandorholozsnyak]

Open @quintesse and @maxandersen - jbangdev/jbang-catalog#11