feat(docs): Add comprehensive CLI documentation suite #301
Conversation
- Complete CLI reference with all commands, options, and examples - Quick start guide for immediate productivity - Troubleshooting guide for common issues - Enhanced tutorial with real-world workflows - Improved installation documentation - Updated navigation and cross-references Transforms fragmented CLI docs into complete, user-friendly documentation.
- Change 'JSON-like data' to 'Ion data' for accuracy - Add link to Ion Fusion website (https://ion-fusion.dev/) - Replace community section with link to website community page - Update performance tips to focus on Fusion-specific optimizations - Add Corretto .deb distribution and MacPorts installation options - Fix missing links in build documentation - Remove accidentally committed gradle.properties and setup script - Update Amazon references to Ion-Fusion where appropriate Addresses feedback from PR ion-fusion#301
|
|
||
| ### Ion Data Format | ||
| Fusion uses Amazon Ion as its data format: | ||
| Fusion uses [Amazon Ion](https://ion-fusion.dev/) as its data format: |
There was a problem hiding this comment.
Sorry for the unclear comment -- I mean we should link to the Amazon Ion official site (i.e https://amazon-ion.github.io/ion-docs/) not the Fusion one
| <!-- Copyright Ion Fusion contributors. All rights reserved. --> | ||
| <!-- SPDX-License-Identifier: Apache-2.0 --> | ||
|
|
||
| # Ion Fusion CLI Reference |
There was a problem hiding this comment.
This seems like it'll end up hard to maintain. Do we have a path forward for auto-generating CLI docs like this from our CLI implementation, once we're moved to a new CLI framework?
|
@mtorres11 So sorry, Marco! For some reason this PR isn't showing up in my Arc PR folder and I lost track of it. I've got a bunch of feedback drafted earlier that I'll clean up and send today. |
toddjonker
left a comment
toddjonker
left a comment
There was a problem hiding this comment.
Hi Marco, thanks for your PR. I really appreciate help with the documentation!
This is a very large PR, so I have a lot of feedback. I'll update the contributing process to better cover documentation, but in general keep in mind that "review early, review often" is the best way to ensure you're work is staying aligned with the code base and its plans.
At a high level, the main concerns here are:
- Content doesn't address target audience
- Document content isn't aligned with Diataxis framework.
- Unnecessary repetition of navigation
- Too many low-level hand-holding.
At a lower level, I think there's too much content. This project is going to be undergoing a lot of change, and everything we document adds costs to those changes. IMO we should aim to be concise and crisp, avoid unnecessary detail, and aim for "once and only once" documentation.
Audience
At the current stage of development, this project's target audience consists of programming-language enthusiasts, not the general public, or even "early adopters". We can (and should) assume that visitors can figure things out given reasonable guidance. We should focus documentation efforts on what's unique about the language and tools. Our goal with all documentation is to discover and develop evangelists.
More to the point: we should not expend much effort speaking to the average developer, except to the degree that we're documenting common Fusion usage. The average developer is not our audience because we currently do not have the resources to support them.
For more insight in how I think about this, watch this video by Simon Sinek.
Diataxis
We follow the Diátaxis framework for documentation, which lays out specific categories of documents and describes how content should be partitioned and approached. We want to ensure that each article fits intentionally into one of those categories, so that content stays focused on desired outcomes.
Navigation
Avoid repetitious navigation aids in each page. These are better served with common navigation frames, which will be possible soon. This includes:
- page-level Table of Contents
- "Getting Help", "Join the Community" sections
- Links to GitHub/Discord/etc
At best, I think an article can end with one or two links guiding the reader to follow-up content. But having more general navigation links all over is giving us a lot of stuff to manually maintain. I'm about to rearrange the whole website structure, and we have no tooling to keep links from breaking, so this is a real issue.
Hand-holding
We don't need to teach them how to install Java, setup PATH, or clone repositories. That level of technical detail will quickly become a maintenance burden and/or outdated.
This PR has thousands of lines of text, and far too much of it is generic, bullet-point content. We really need to be much more focused on high-quality explanations of non-obvious things. We don't need to enumerate and have examples of every trivial feature and/or interaction.
Recommendation
I strongly recommend that you come at this in smaller chunks, so we can align on goals, structure, and voice by focusing on smaller increments of work. I think the CLI Reference is the most valuable part here, and I'd love to see a review for just that, adjusted per the feedback here.
| ### Option 1: Build from Source (Recommended) | ||
|
|
||
| **Prerequisites:** | ||
| - Java 8 or later ([Corretto](https://aws.amazon.com/corretto/) recommended) | ||
| - Git | ||
|
|
||
| **Steps:** | ||
| ```bash | ||
| # Clone the repository | ||
| git clone https://github.com/ion-fusion/fusion-java.git | ||
| cd fusion-java | ||
|
|
||
| # Build the CLI | ||
| ./gradlew release | ||
|
|
||
| # Add to PATH | ||
| export PATH=$PATH:$PWD/build/install/fusion/bin | ||
|
|
||
| # Verify installation | ||
| fusion version | ||
| ``` | ||
|
|
||
| ### Option 2: Download Pre-built Binary *(Coming Soon)* | ||
|
|
||
| Pre-built binaries will be available from the [releases page](https://github.com/ion-fusion/fusion-java/releases) once version 1.0 is released. | ||
|
|
||
| ## First Steps |
There was a problem hiding this comment.
Personally, I'd rather recommend use of a snapshot build (already at that link), over building from source.
| <!-- Copyright Ion Fusion contributors. All rights reserved. --> | ||
| <!-- SPDX-License-Identifier: Apache-2.0 --> | ||
|
|
||
| # Ion Fusion CLI Quick Start |
There was a problem hiding this comment.
Where do you see this documentation fitting within Diátaxis?
Personally, I am not a fan of "quickstart" documents because they are almost always grab-bags of content without any specific goal.
Each document in this tree should have a specific intended outcome. What is the specific outcome that this document aims to achieve for a reader?
| ### `--bootstrapRepository DIR` *(Deprecated)* | ||
| **⚠️ DEPRECATED:** This option is deprecated. If used, the directory is treated as the first user repository (equivalent to `--repositories`). |
There was a problem hiding this comment.
We can omit this from the docs. And probably can delete the corresponding code.
| Evaluates Fusion expressions provided as command-line arguments. | ||
| **Syntax:** `eval EXPRESSIONS` |
There was a problem hiding this comment.
This doc (and the help content) is misleading; this only accepts one expression at the moment. Meaning, fusion eval 1 2 gives an error.
I'm inclined to fix the CLI so it accepts multiple argument-expressions. Shouldn't be hard, interested in doing that? (Don't do it in this PR tho)
| Evaluates the given expressions as top-level Fusion forms. If the result of the last expression is not void, it's written to standard output using Ion format. | ||
There was a problem hiding this comment.
It's a bit more subtle, since a single expression can return multiple values. In which case they are each printed, one per line:
% build/install/fusion/bin/fusion eval '(values 1 2)'
1
2
Normally we'd skip this detail, but since this is the reference it belongs here.
| **Examples:** | ||
| ```bash | ||
| # Import string utilities | ||
| fusion require '/fusion/string' ';' eval '(string_length "hello")' | ||
| # Output: 5 | ||
|
|
||
| # Import and use struct operations | ||
| fusion require '/fusion/struct' ';' eval '(define s (mutable_struct "a" 1)) (put_m s "b" 2) s' | ||
| # Output: {a:1,b:2} | ||
|
|
||
| # Chain multiple requires | ||
| fusion require '/fusion/list' ';' require '/fusion/string' ';' eval '(map string_length ["a" "bb" "ccc"])' | ||
| # Output: [1,2,3] | ||
| ``` |
There was a problem hiding this comment.
Examples have more value when accompanied by explanations. Connect the dots for the reader. Each one should teach one specific, useful concept.
| **Module Resolution:** | ||
| - Module IDs are absolute paths starting with `/` | ||
| - Standard library modules are under `/fusion/` | ||
| - User modules depend on repository configuration | ||
| **Common Modules:** | ||
| - `/fusion/string` - String manipulation functions | ||
| - `/fusion/list` - List processing utilities | ||
| - `/fusion/struct` - Structure operations | ||
| - `/fusion/io` - Input/output operations | ||
| - `/fusion/number` - Numeric functions |
| ## Command Chaining | ||
| Multiple commands can be executed in sequence by separating them with semicolons (`;`). All commands share the same namespace, so definitions and imports from earlier commands are available to later ones. | ||
| **Syntax:** | ||
| ```bash | ||
| fusion command1 args ';' command2 args ';' command3 args | ||
| ``` | ||
| **Shell Escaping:** | ||
| In most shells, semicolons need to be escaped or quoted: | ||
| ```bash | ||
| # Escaped semicolon | ||
| fusion require /fusion/string \; eval '(string_length "test")' | ||
| # Quoted semicolon | ||
| fusion require /fusion/string ';' eval '(string_length "test")' | ||
| ``` | ||
| **Examples:** | ||
| ```bash | ||
| # Setup and execution | ||
| fusion require '/fusion/list' ';' eval '(define nums [1 2 3 4 5])' ';' eval '(fold + 0 nums)' | ||
| # Load configuration then run script | ||
| fusion load config.fusion ';' load main.fusion | ||
| # Interactive session with preloaded modules | ||
| fusion require '/fusion/string' ';' require '/fusion/list' ';' repl | ||
| ``` | ||
| **Namespace Sharing:** | ||
| - Variables defined in one command are available in subsequent commands | ||
| - Module imports persist across commands | ||
| - Error in one command stops execution of remaining commands |
There was a problem hiding this comment.
This is particularly unique to this CLI, so it should be more prominant.
| ## Examples | ||
| ### Data Processing Pipeline | ||
| Process JSON data through multiple transformation steps: | ||
| ```bash | ||
| # Process JSON data with transformations | ||
| echo '{"users": [{"name": "Alice", "age": 25}, {"name": "Bob", "age": 30}]}' | \ | ||
| fusion eval '(define data (read))' ';' \ | ||
| eval '(define users (. data "users"))' ';' \ | ||
| eval '(map (lambda (user) (. user "name")) users)' | ||
| ``` | ||
| ### Module Development Workflow | ||
| Develop and test a custom module: | ||
| ```bash | ||
| # Load module and test interactively | ||
| fusion --repositories ./my-modules require '/myproject/utils' ';' repl | ||
| # Run tests with coverage | ||
| fusion --repositories ./my-modules load test-suite.fusion ';' \ | ||
| report_coverage ./coverage-data ./coverage-report | ||
| ``` | ||
| ### Batch Processing | ||
| Process multiple files with the same script: | ||
| ```bash | ||
| # Process each file in a directory | ||
| for file in data/*.ion; do | ||
| echo "Processing $file" | ||
| fusion load process-data.fusion < "$file" > "processed/$(basename "$file")" | ||
| done | ||
| ``` | ||
| ### Configuration and Execution | ||
| Load configuration and run application: | ||
| ```bash | ||
| # Production deployment | ||
| fusion --repositories /opt/fusion-modules \ | ||
| --catalogs /opt/ion-catalogs \ | ||
| load config/production.fusion ';' \ | ||
| load app/main.fusion | ||
| ``` | ||
There was a problem hiding this comment.
None of this is Reference material, it belongs in other quadrants of Diataxis.
| <!-- Copyright Ion Fusion contributors. All rights reserved. --> | ||
| <!-- SPDX-License-Identifier: Apache-2.0 --> | ||
|
|
||
| # Ion Fusion CLI Reference |
There was a problem hiding this comment.
This is the most important part of this PR. But it's also far too long. I encourage you to edit this down to about half the length.
There are no bonus points for document size or verbosity. Especially in reference material, crisp and concise wins every time.
5 participants
Transforms fragmented CLI docs into complete, user-friendly documentation.
Description
What does this change achieve?
Related Issues
What issue(s) does this change address?
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.