-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc(book): extend the docs about cli and generators
Extend the docs around these sections and create an example in `mabo-cli` which auto-generates the doc pages for the CLI subcommands.
- Loading branch information
Showing
16 changed files
with
307 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,28 @@ | ||
--- | ||
editLink: false | ||
lastUpdated: false | ||
--- | ||
|
||
# mabo check | ||
|
||
- Aliases: `c` | ||
|
||
Check that a project or set of files are valid schemas. | ||
|
||
This involves first checking each schema individually to be parseable, then run various lints over it and finally resolve any external schema types. In case any of the steps fail an error will be returned. | ||
|
||
## Arguments | ||
|
||
### `FILES` | ||
|
||
Loose list of glob patterns for files that should be checked instead of a project. | ||
|
||
Using this will disable the loading of a project and instead locate the files from the glob patterns, then treat them as one single set. The files will be treated as a single project but the `Mabo.toml` file is fully ignored. | ||
|
||
## Options | ||
|
||
### `--project-dir` | ||
|
||
Alternative location of the project directory containing a `Mabo.toml` file. | ||
|
||
By default, the current directory is assumed to be the project directory. This is the root from where the command operates. Therefore, using it has the same effect as moving to the project directory and executing the command without it. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,26 @@ | ||
--- | ||
editLink: false | ||
lastUpdated: false | ||
--- | ||
|
||
# mabo doc | ||
|
||
- Aliases: `d`, `document` | ||
|
||
Generate documentation for a project. | ||
|
||
## Arguments | ||
|
||
### `OUT_DIR` | ||
|
||
Directory where the documentation files are written to. | ||
|
||
Note that this directory will be overwritten without confirmation. Any existing files will be replaced, but the directory is not fully cleared beforehand. That means any unrelated files not having the same name as any documentation file, will remain. | ||
|
||
## Options | ||
|
||
### `--project-dir` | ||
|
||
Alternative location of the project directory containing a `Mabo.toml` file. | ||
|
||
By default, the current directory is assumed to be the project directory. This is the root from where the command operates. Therefore, using it has the same effect as moving to the project directory and executing the command without it. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,26 @@ | ||
--- | ||
editLink: false | ||
lastUpdated: false | ||
--- | ||
|
||
# mabo fmt | ||
|
||
- Aliases: `f`, `format` | ||
|
||
Format a project or set of files. | ||
|
||
## Arguments | ||
|
||
### `FILES` | ||
|
||
Loose list of glob patterns for files that should be formatted instead of a project. | ||
|
||
Using this will disable the loading of a project and instead locate the files from the glob patterns, then treat them as one single set. The files will be treated as a single project but the `Mabo.toml` file is fully ignored. | ||
|
||
## Options | ||
|
||
### `--project-dir` | ||
|
||
Alternative location of the project directory containing a `Mabo.toml` file. | ||
|
||
By default, the current directory is assumed to be the project directory. This is the root from where the command operates. Therefore, using it has the same effect as moving to the project directory and executing the command without it. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
# Command Line Interface | ||
|
||
To ease and support the development of Mabo schema files, a variety of tools are available. These are all bundled together into a single binary that can be utilized through the terminal. | ||
|
||
The following pages describe the details of each available command. | ||
|
||
## Installation | ||
|
||
Available installation methods are described on the [installation](../../guide/installation#command-line-interface) page of the user guide. | ||
|
||
## Global options | ||
|
||
These options are available to all commands, when invoking the plain application or using any of the sub-commands described in the following pages. | ||
|
||
### `-h`, `--help` | ||
|
||
Print the help text for the program or command, explaining each argument and option available. This is in fact the same information as available here. | ||
|
||
### `-V`, `--version` | ||
|
||
Print the version of the program. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,26 @@ | ||
--- | ||
editLink: false | ||
lastUpdated: false | ||
--- | ||
|
||
# mabo init | ||
|
||
- Aliases: `i`, `initialize` | ||
|
||
Initialize a new project. | ||
|
||
## Arguments | ||
|
||
### `PATH` | ||
|
||
Alternative path were the project should be generated. | ||
|
||
By default, the current directory is assumed to be the to-be project directory. This is where the `Mabo.toml` file will be placed to mark it as project. Therefore, the path must point to a directory, not a file. | ||
|
||
## Options | ||
|
||
### `--name` | ||
|
||
Name of the project. If omitted, the name is derived from the current working directory. | ||
|
||
This is used as the project name in the `Mabo.toml` file to give it a unique identifier. It must only be unique within the project (in case it has multiple projects). |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,9 @@ | ||
# Documentation | ||
|
||
The `doc` generator does not generate source code, but instead documentation for a Mabo project. It interprets comments as [Markdown](https://daringfireball.net/projects/markdown/) and renders static pages for each element. | ||
|
||
This generator is not available as a standalone binary but instead available through the Mabo command line interface with the [mabo doc](../cli/doc) command. | ||
|
||
## Hosting | ||
|
||
The documentation output consists of static files that can be hosted by any static file host. A common and easy way is to use **GitHub Pages**. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,3 @@ | ||
# Go | ||
|
||
[runtime library](https://github.com/dnaka91/mabo-go) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,18 @@ | ||
# Generators | ||
|
||
Code generators are the part of Mabo that turn the schema into actual source code that can be consumed by projects. | ||
|
||
The sub-sections describe details for all the officially supported generators. These are all written in Rust, but these are not limited to one language. | ||
|
||
The mabo compiler can output the parsed schemas in [JSON](https://www.json.org/json-en.html), a data format very common and widespread. Therefore, generators can be written in any language, consume the output and turn it into source code. | ||
|
||
## How generators work | ||
|
||
Each generator is usually paired with a runtime library to make the generated code work. This handles the low-level workings of the format like encoding individual values. | ||
|
||
How a generator is invoked depends on the language. For example: | ||
|
||
- Go projects call a binary to generate the code and include the output directly in the repository. | ||
- Java projects use a Gradle plugin to generate the data structures on the fly. | ||
- JavaScript and TypeScript projects use a bundler plugin to generate the data structures. | ||
- Rust projects use a `build.rs` build script file to generate the data structures. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,3 @@ | ||
# Kotlin | ||
|
||
[runtime library](https://github.com/dnaka91/mabo-kt) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,3 @@ | ||
# Python | ||
|
||
[runtime library](https://github.com/dnaka91/mabo-py) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,3 @@ | ||
# Typescript | ||
|
||
[runtime library](https://github.com/dnaka91/mabo-ts) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,85 @@ | ||
//! Helper that renders all the CLI sub-commands and arguments into Markdown files for the book. | ||
//! | ||
//! Should be run whenever there are changes to the `src/cli.rs` file to reflect the changes in the | ||
//! book accordingly. | ||
|
||
use std::{fmt::Write, fs, path::Path}; | ||
|
||
use anyhow::{Context, Result}; | ||
use clap::CommandFactory; | ||
|
||
use self::cli::Cli; | ||
|
||
#[allow(dead_code)] | ||
#[path = "../src/cli.rs"] | ||
mod cli; | ||
|
||
fn main() -> Result<()> { | ||
let base = concat!(env!("CARGO_MANIFEST_DIR"), "/../../book/src/reference/cli/"); | ||
let base = Path::new(base).canonicalize()?; | ||
|
||
let cmd = Cli::command(); | ||
for sub in cmd.get_subcommands() { | ||
let mut buf = "---\n".to_owned(); | ||
writeln!(&mut buf, "editLink: false")?; | ||
writeln!(&mut buf, "lastUpdated: false")?; | ||
writeln!(&mut buf, "---")?; | ||
|
||
writeln!(&mut buf, "\n# {} {}", cmd.get_name(), sub.get_name())?; | ||
|
||
for (i, alias) in sub.get_visible_aliases().enumerate() { | ||
if i == 0 { | ||
write!(&mut buf, "\n- Aliases: ")?; | ||
} else { | ||
write!(&mut buf, ", ")?; | ||
} | ||
write!(&mut buf, "`{alias}`")?; | ||
} | ||
|
||
if sub.get_visible_aliases().next().is_some() { | ||
writeln!(&mut buf)?; | ||
} | ||
|
||
if let Some(about) = sub.get_long_about() { | ||
writeln!(&mut buf, "\n{about}")?; | ||
} else if let Some(about) = sub.get_about() { | ||
writeln!(&mut buf, "\n{about}.")?; | ||
} | ||
|
||
writeln!(&mut buf, "\n## Arguments")?; | ||
for arg in sub.get_positionals() { | ||
writeln!( | ||
&mut buf, | ||
"\n### `{}`", | ||
arg.get_value_names() | ||
.context("no value name for positional arg")?[0] | ||
)?; | ||
|
||
if let Some(help) = arg.get_long_help() { | ||
writeln!(&mut buf, "\n{help}")?; | ||
} else if let Some(help) = arg.get_help() { | ||
writeln!(&mut buf, "\n{help}.")?; | ||
} | ||
} | ||
|
||
writeln!(&mut buf, "\n## Options")?; | ||
for arg in sub.get_opts() { | ||
match (arg.get_long(), arg.get_short()) { | ||
(Some(long), Some(short)) => writeln!(&mut buf, "\n### `-{short}`, `--{long}`"), | ||
(Some(long), None) => writeln!(&mut buf, "\n### `--{long}`"), | ||
(None, Some(short)) => writeln!(&mut buf, "\n### `-{short}`"), | ||
(None, None) => continue, | ||
}?; | ||
|
||
if let Some(help) = arg.get_long_help() { | ||
writeln!(&mut buf, "\n{help}")?; | ||
} else if let Some(help) = arg.get_help() { | ||
writeln!(&mut buf, "\n{help}.")?; | ||
} | ||
} | ||
|
||
fs::write(base.join(format!("{}.md", sub.get_name())), buf)?; | ||
} | ||
|
||
Ok(()) | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters