Skip to content

feat(docs): add fluxdoc formatting documentation #4210

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 5, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 16 additions & 13 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Contributing to Flux
# Contribute to Flux

## Community Slack Channel
When contributing to Flux, it is a good idea to join the [community Slack channel](https://www.influxdata.com/slack).
The development team for Flux is in the `#flux` channel and we will be able to answer any questions or give any recommendations for development work from there.

## Filing issues
## File issues
Filing issues on GitHub is one of the easiest and most useful ways to contribute to Flux.
We value every request and we intend to triage every community issue within a week after it has been created.
If it takes us longer than a week, then please try to contact us in the community Slack channel.
@@ -31,18 +31,18 @@ We really like to receive feature requests as they help us prioritize our work.
Please be clear about your requirements. Incomplete feature requests may simply
be closed if we don't understand what you would like to see added to Flux.

## Contributing to the source code
## Contribute to the source code

### Signing the CLA
### Sign the CLA
In order to contribute back to Flux, you must sign the
[InfluxData Contributor License Agreement](https://www.influxdata.com/legal/cla/) (CLA).

### Finding an issue
### Find an issue
The Flux team regularly adds the [community](https://github.com/influxdata/flux/issues?q=is%3Aopen+is%3Aissue+label%3Acommunity) label to issues that we think would be accessible for a community member to take.
Before starting to work on an issue, please inform us on GitHub about your intention to work on the issue by leaving a comment on the issue.
This allows us to know that you want to work on the issue, that the issue is updated with the needed information, and to be ready for a pull request when the work is done.

### Contributing to the source code
### Contribute to the source code
Flux uses Go modules and requires modules to be enabled to build from source.
Please refer to the Go documentation on [modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more) for more information about how to enable module builds.
To build and test the software, the following developer dependencies are required:
@@ -64,15 +64,15 @@ $ go test ./...

If you use `go generate` on the scanner package, then the Ragel version above is needed to correctly generate the files.

### Regenerating the standard library
### Regenerate the standard library
If you modify any `.flux` files in the repository, the standard library must be regenerated.
This is done by running `go generate` in the following way.

```bash
$ go generate ./stdlib
```

### Regenerating checksums
### Regenerate checksums

If you modify any `.rs` files in the repository, checksums must be recomputed.
This allows the Go–Rust interaction to work appropriately.
@@ -82,11 +82,10 @@ From the repository root, run
$ make generate
```

### Contributing Flux Packages
### Contribute Flux Packages

If you have some Flux code that you think the wider community would benifit from please consider contributing it to the Flux repo.
We have layed out specific guildines in the contrib [README](https://github.com/influxdata/flux/blob/master/stdlib/contrib/README.md).
uu
We have layed out specific guidelines in the contrib [README](https://github.com/influxdata/flux/blob/master/stdlib/contrib/README.md).

## Pull request guidelines

@@ -131,15 +130,19 @@ Every new public function or method requires a valid GoDoc.
Comments within the code should be written with proper capitalization and punctuation at the end of the sentence.
Please refer to [this blog post](https://blog.golang.org/godoc-documenting-go-code) about documenting Go code.

### Updating markdown files for documentation
### Update markdown files for documentation
The Flux team uses markdown for our documentation.
When writing markdown, please use the following guidelines:

- Each sentence in a paragraph is on its own line.
- Use the `#` symbol for header sections.
- Use the `-` symbol for bullet points.

## Submitting a pull request
#### Document Flux package source code
When documenting Flux packages, use fluxdoc-compliant comments in your Flux source code.
For more information, see [fluxdoc formatting](https://github.com/influxdata/flux/blob/master/docs/fluxdoc.md).

## Submit a pull request
To submit a pull request you should fork the Flux repository and make your change on a feature branch of your fork.
Then generate a pull request from your branch against **master** of the Flux repository.
Include in your pull request details of your change -- the **why** *and* the **how** -- as well as the testing you performed.
240 changes: 240 additions & 0 deletions docs/fluxdoc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,240 @@
# fluxdoc formatting

`fluxdoc` uses comments in `.flux` package files in `/stdlib` to generate and
output standard library documentation in JSON format.
The generated JSON is used to build the public-facing Flux standard library
documentation and ensure documentation is up-to-date and featur-complete with
each new Flux release.

## Syntax and structure
Each `.flux` package file in `/stdlib` should include comments using the
following syntax and structure.
Flux comment lines begin with `//`.

### Use Markdown
Inline Flux documentation uses Markdown or, more specifically,
[CommonMark)](https://spec.commonmark.org/).
For consistency, use the the following Markdown conventions:

- `#` header syntax
- `-` character for lists
- Fenced codeblocks

### Package summary documentation
Add package summary documentation before the package statement in the `.flux` package file.
Package summary documentation consists of a **headline**, **description**,
**examples**, and **metadata** to be used by clients when consuming the JSON `fluxdoc` output.

- **headline**: _First paragraph_ of the package documentation that describes
what the package does. Must begin with `Package <pkg-name>`.
- **description** _(Optional)_: All paragraphs between the first paragraph and
optional metadata. Provides additional details about the package.
- **examples** _(Optional)_: _See [Package and function examples](#package-and-function-examples)._
- **metadata** _(Optional)_: Metadata that provides helpful information about
the package. _See [Package metadata](#package-metadata)_.

#### Package metadata
Package metadata are string key-value pairs separated by `:`.
Each key-value pair must be on a single line.

- **introduced**: Flux version the package was added _(Strongly encouraged)_.
- **deprecated**: Flux version the package was deprecated.
- **tags**: Comma-separated list of tags used to associate related documentation
and categorize packages. _See [Metadata tags](#metadata-tags)._
- **contributors**: Contributor GitHub usernames or other contact information.

```js
// Package examplePkg provides functions that do x and y.
//
// Package description with additional details not provided in the headline.
//
// ## Examples
// ```
// import "examplePkg"
//
// examplePkg.foo()
// ```
//
// introduced: 0.123.0
// tags: tag1,tag2,tag3
// contributors: [@someuser](https://github.com/someuser) (GitHub)
package examplePkg
```

### Function documentation
Add function documentation before the function definition in the `.flux` package file.
Function documentation consists of a **headline**, **description**,
**parameters**, **examples**, and **metadata** to be used by clients when
consuming the JSON `fluxdoc` output.

- **headline**: _First paragraph_ of the function documentation that describes
what the function does. Must begin with the _function name_ (case sensitive).
- **description** _(Optional)_: All paragraphs between the first paragraph and
parameters. Provides additional details about the function.
- **parameters**: _See [Function parameters](#function-parameters)._
- **examples**: _(Optional)_: _See [Package and function examples](#package-and-function-examples)._
- **metadata** _(Optional)_: Metadata that provides helpful information about
the package. _See [Function metadata](#function-metadata)._

#### Function parameters
Identify the beginning of the parameter list with the `## Parameters` header.
List parameters as a markdown unordered list.
Each list item must follow these conventions:

- Use the `-` character when formatting the list.
- Begin each item with the parameter name (case-sensitive) followed by a colon (`:`).
- Provide a description of the parameter after the parameter name and colon.

##### Parameter description guidelines
- The first paragraph of the parameter description is used as the short description.
- The first paragraph and all subsequent content are used as the long description.
- Parameter descriptions can contain any valid markdown.
If there are multiple paragraphs, lists, or other elements that need to be
included in the description, indent them them under the parameter list item to
nest them as part of the parameter description.
- Avoid starting parameter descriptions with an article (the, a, an).
For example:

```md
<!-- Not recommended -->
- param: The value to multiply.
- param: A value to multiply.

<!-- Recommended -->
- param: Value to multiply.
```
- If a parameter has a default value, specify the default in the description
with "Default is `defaultValue`."

#### Package and function examples
Identify the beginning of the examples list with the `## Examples` header.
Identify each example with a descriptive title formatted as an h3 header
(`### Example descriptive title`).

##### Example guidelines
- In example titles, use imperative voice and avoid gerunds (verbs ending in
"ing" and used as a noun). For example, use "Filter by tag" instead of
"Filtering by tag."
- Use fenced code blocks to identify the example code.
- If an example uses a syntax other than Flux, include the language identifier
with the fenced codeblock. If the Flux example should not be executed, use
`no_run` as the language identifier.
- Examples should pass the `flux fmt` formatting check.

##### Example execution, input, and output
Each example, if possible, should be able to be run as a standalone script.
This allows Flux to actually execute the examples to both test the validity of
the example and provide actual example input and output.
Use the `array`, `csv`, or `sampledata` packages to include data as part of the
examples.

Use the following conventions to control example execution, input, and output.

- `# ` omits the line from the rendered example, but keeps the line during example execution.
- `< ` at the beginning of a line appends a `yield` to the end of the line to specify input.
The `input` yield is parsed into Markdown tables and included with the JSON documentation output.
- `> ` at the beginning of a line appends a `yield` to the ind of the line to specify output.
The `output` yield is parsed into Markdown tables and included with the JSON documentation output.
- To skip example execution, use the `no_run` language identifier on the code block.

```js
// ## Examples
//
// ### Filter by tag value
// ```
// # import "sampledata"
//
// < sampledata.float()
// > |> filter(fn: (r) => r.tag == "t1")
// ```
```

#### Function metadata
Function metadata are string key-value pairs separated by `:`.
Each key-value pair must be on a single line.

- **introduced**: Flux version the function was added _(if different than the package)_.
- **deprecated**: Flux version the function was deprecated _(if different than the package)_.
- **tags**: Comma-separated list of tags used to associate related documentation
and categorize functions. _See [Metadata tags](#metadata-tags)._

### Metadata tags
While tags are somewhat arbitrary, some are used to categorize functions.
Use the following tags to categorize functions based on their usage and functionality:

- **aggregates**: Add to aggregate functions (functions that aggregate all rows
in a table into a single row).
- **date/time**: Add to date/time-related functions.
- **dynamic queries**: Add to functions that convert streams of tables into
another composite or basic type.
- **filters**: Add to functions that filter data.
- **geotemporal**: Add to geotemporal-related functions.
- **GIS**: Add to GIS-related functions.
- **inputs**: Add to functions the retrieve data from a data source.
- **metadata**: Add to functions that return metadata from input tables or a
data source.
- **notification endpoints**: Add to notification endpoint functions.
- **outputs**: Add to functions to output data to a data source.
- **sample data**: Add to functions the provide sample data.
- **selectors**: Add to selector functions (functions that select rows from each
input table).
- **single notification**: Add to functions that send a single notification.
- **tests**: Add to functions that perform tests.
- **transformations**: Add to transformations (functions that take a stream of
tables as input and output a stream of tables).
- **type-conversions**: Add to functions that change data types.

## Full package documentation example
```js
// Package pkgName provides functions that do x and y.
//
// ## Examples
// ```
// import "pkgName"
//
// option pkgName.foo == "bar'
// ```
//
// introduced: 0.140.0
// contributors: [@username](https://github.com/username/) (GitHub)
package pkgName

// myFn multiplies `x` by `y`.
//
// ## Parameters
// - x: Left operand.
// - y: Right operand.
//
// ## Examples
//
// ### Multiply x and y
// ```no_run
// import "pkgName"
//
// pkgName.myFn(x: 2, y: 4)
// // Returns 8
// ```
//
myFn = (x, y) => x * y

// anotherFn drops columns from input tables.
//
// ## Parameters
// - columns: List of columns to drop.
// - tables: Input data. Default is piped-forward data.
//
// ## Examples
//
// ### Drop specific columns
// ```
// import "sampledata"
// import "pkgName"
//
// < sampledata.float()
// > |> pkgName.anotherFn(columns: [tag])
// ```
//
// introduced: 0.141.0
// tags: transformations
anotherFn = (columns, tables=<-) => tables |> drop(columns: columns)
```