Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit bb6deba

Browse files
sandersonpierwill
sanderson
authored and
pierwill
committedNov 8, 2021
feat(docs): add fluxdoc formatting documentation (#4210)
* feat(docs): add fluxdoc formatting documentation * feat(docs): add package examples and long param descriptions to fluxdoc readme
1 parent 5f697c0 commit bb6deba

File tree

2 files changed

+256
-13
lines changed

2 files changed

+256
-13
lines changed
 

‎CONTRIBUTING.md

+16-13
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Contributing to Flux
1+
# Contribute to Flux
22

33
## Community Slack Channel
44
When contributing to Flux, it is a good idea to join the [community Slack channel](https://www.influxdata.com/slack).
55
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.
66

7-
## Filing issues
7+
## File issues
88
Filing issues on GitHub is one of the easiest and most useful ways to contribute to Flux.
99
We value every request and we intend to triage every community issue within a week after it has been created.
1010
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.
3131
Please be clear about your requirements. Incomplete feature requests may simply
3232
be closed if we don't understand what you would like to see added to Flux.
3333

34-
## Contributing to the source code
34+
## Contribute to the source code
3535

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

40-
### Finding an issue
40+
### Find an issue
4141
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.
4242
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.
4343
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.
4444

45-
### Contributing to the source code
45+
### Contribute to the source code
4646
Flux uses Go modules and requires modules to be enabled to build from source.
4747
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.
4848
To build and test the software, the following developer dependencies are required:
@@ -64,15 +64,15 @@ $ go test ./...
6464

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

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

7171
```bash
7272
$ go generate ./stdlib
7373
```
7474

75-
### Regenerating checksums
75+
### Regenerate checksums
7676

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

85-
### Contributing Flux Packages
85+
### Contribute Flux Packages
8686

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

9190
## Pull request guidelines
9291

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

134-
### Updating markdown files for documentation
133+
### Update markdown files for documentation
135134
The Flux team uses markdown for our documentation.
136135
When writing markdown, please use the following guidelines:
137136

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

142-
## Submitting a pull request
141+
#### Document Flux package source code
142+
When documenting Flux packages, use fluxdoc-compliant comments in your Flux source code.
143+
For more information, see [fluxdoc formatting](https://github.com/influxdata/flux/blob/master/docs/fluxdoc.md).
144+
145+
## Submit a pull request
143146
To submit a pull request you should fork the Flux repository and make your change on a feature branch of your fork.
144147
Then generate a pull request from your branch against **master** of the Flux repository.
145148
Include in your pull request details of your change -- the **why** *and* the **how** -- as well as the testing you performed.

‎docs/fluxdoc.md

+240
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# fluxdoc formatting
2+
3+
`fluxdoc` uses comments in `.flux` package files in `/stdlib` to generate and
4+
output standard library documentation in JSON format.
5+
The generated JSON is used to build the public-facing Flux standard library
6+
documentation and ensure documentation is up-to-date and featur-complete with
7+
each new Flux release.
8+
9+
## Syntax and structure
10+
Each `.flux` package file in `/stdlib` should include comments using the
11+
following syntax and structure.
12+
Flux comment lines begin with `//`.
13+
14+
### Use Markdown
15+
Inline Flux documentation uses Markdown or, more specifically,
16+
[CommonMark)](https://spec.commonmark.org/).
17+
For consistency, use the the following Markdown conventions:
18+
19+
- `#` header syntax
20+
- `-` character for lists
21+
- Fenced codeblocks
22+
23+
### Package summary documentation
24+
Add package summary documentation before the package statement in the `.flux` package file.
25+
Package summary documentation consists of a **headline**, **description**,
26+
**examples**, and **metadata** to be used by clients when consuming the JSON `fluxdoc` output.
27+
28+
- **headline**: _First paragraph_ of the package documentation that describes
29+
what the package does. Must begin with `Package <pkg-name>`.
30+
- **description** _(Optional)_: All paragraphs between the first paragraph and
31+
optional metadata. Provides additional details about the package.
32+
- **examples** _(Optional)_: _See [Package and function examples](#package-and-function-examples)._
33+
- **metadata** _(Optional)_: Metadata that provides helpful information about
34+
the package. _See [Package metadata](#package-metadata)_.
35+
36+
#### Package metadata
37+
Package metadata are string key-value pairs separated by `:`.
38+
Each key-value pair must be on a single line.
39+
40+
- **introduced**: Flux version the package was added _(Strongly encouraged)_.
41+
- **deprecated**: Flux version the package was deprecated.
42+
- **tags**: Comma-separated list of tags used to associate related documentation
43+
and categorize packages. _See [Metadata tags](#metadata-tags)._
44+
- **contributors**: Contributor GitHub usernames or other contact information.
45+
46+
```js
47+
// Package examplePkg provides functions that do x and y.
48+
//
49+
// Package description with additional details not provided in the headline.
50+
//
51+
// ## Examples
52+
// ```
53+
// import "examplePkg"
54+
//
55+
// examplePkg.foo()
56+
// ```
57+
//
58+
// introduced: 0.123.0
59+
// tags: tag1,tag2,tag3
60+
// contributors: [@someuser](https://github.com/someuser) (GitHub)
61+
package examplePkg
62+
```
63+
64+
### Function documentation
65+
Add function documentation before the function definition in the `.flux` package file.
66+
Function documentation consists of a **headline**, **description**,
67+
**parameters**, **examples**, and **metadata** to be used by clients when
68+
consuming the JSON `fluxdoc` output.
69+
70+
- **headline**: _First paragraph_ of the function documentation that describes
71+
what the function does. Must begin with the _function name_ (case sensitive).
72+
- **description** _(Optional)_: All paragraphs between the first paragraph and
73+
parameters. Provides additional details about the function.
74+
- **parameters**: _See [Function parameters](#function-parameters)._
75+
- **examples**: _(Optional)_: _See [Package and function examples](#package-and-function-examples)._
76+
- **metadata** _(Optional)_: Metadata that provides helpful information about
77+
the package. _See [Function metadata](#function-metadata)._
78+
79+
#### Function parameters
80+
Identify the beginning of the parameter list with the `## Parameters` header.
81+
List parameters as a markdown unordered list.
82+
Each list item must follow these conventions:
83+
84+
- Use the `-` character when formatting the list.
85+
- Begin each item with the parameter name (case-sensitive) followed by a colon (`:`).
86+
- Provide a description of the parameter after the parameter name and colon.
87+
88+
##### Parameter description guidelines
89+
- The first paragraph of the parameter description is used as the short description.
90+
- The first paragraph and all subsequent content are used as the long description.
91+
- Parameter descriptions can contain any valid markdown.
92+
If there are multiple paragraphs, lists, or other elements that need to be
93+
included in the description, indent them them under the parameter list item to
94+
nest them as part of the parameter description.
95+
- Avoid starting parameter descriptions with an article (the, a, an).
96+
For example:
97+
98+
```md
99+
<!-- Not recommended -->
100+
- param: The value to multiply.
101+
- param: A value to multiply.
102+
103+
<!-- Recommended -->
104+
- param: Value to multiply.
105+
```
106+
- If a parameter has a default value, specify the default in the description
107+
with "Default is `defaultValue`."
108+
109+
#### Package and function examples
110+
Identify the beginning of the examples list with the `## Examples` header.
111+
Identify each example with a descriptive title formatted as an h3 header
112+
(`### Example descriptive title`).
113+
114+
##### Example guidelines
115+
- In example titles, use imperative voice and avoid gerunds (verbs ending in
116+
"ing" and used as a noun). For example, use "Filter by tag" instead of
117+
"Filtering by tag."
118+
- Use fenced code blocks to identify the example code.
119+
- If an example uses a syntax other than Flux, include the language identifier
120+
with the fenced codeblock. If the Flux example should not be executed, use
121+
`no_run` as the language identifier.
122+
- Examples should pass the `flux fmt` formatting check.
123+
124+
##### Example execution, input, and output
125+
Each example, if possible, should be able to be run as a standalone script.
126+
This allows Flux to actually execute the examples to both test the validity of
127+
the example and provide actual example input and output.
128+
Use the `array`, `csv`, or `sampledata` packages to include data as part of the
129+
examples.
130+
131+
Use the following conventions to control example execution, input, and output.
132+
133+
- `# ` omits the line from the rendered example, but keeps the line during example execution.
134+
- `< ` at the beginning of a line appends a `yield` to the end of the line to specify input.
135+
The `input` yield is parsed into Markdown tables and included with the JSON documentation output.
136+
- `> ` at the beginning of a line appends a `yield` to the ind of the line to specify output.
137+
The `output` yield is parsed into Markdown tables and included with the JSON documentation output.
138+
- To skip example execution, use the `no_run` language identifier on the code block.
139+
140+
```js
141+
// ## Examples
142+
//
143+
// ### Filter by tag value
144+
// ```
145+
// # import "sampledata"
146+
//
147+
// < sampledata.float()
148+
// > |> filter(fn: (r) => r.tag == "t1")
149+
// ```
150+
```
151+
152+
#### Function metadata
153+
Function metadata are string key-value pairs separated by `:`.
154+
Each key-value pair must be on a single line.
155+
156+
- **introduced**: Flux version the function was added _(if different than the package)_.
157+
- **deprecated**: Flux version the function was deprecated _(if different than the package)_.
158+
- **tags**: Comma-separated list of tags used to associate related documentation
159+
and categorize functions. _See [Metadata tags](#metadata-tags)._
160+
161+
### Metadata tags
162+
While tags are somewhat arbitrary, some are used to categorize functions.
163+
Use the following tags to categorize functions based on their usage and functionality:
164+
165+
- **aggregates**: Add to aggregate functions (functions that aggregate all rows
166+
in a table into a single row).
167+
- **date/time**: Add to date/time-related functions.
168+
- **dynamic queries**: Add to functions that convert streams of tables into
169+
another composite or basic type.
170+
- **filters**: Add to functions that filter data.
171+
- **geotemporal**: Add to geotemporal-related functions.
172+
- **GIS**: Add to GIS-related functions.
173+
- **inputs**: Add to functions the retrieve data from a data source.
174+
- **metadata**: Add to functions that return metadata from input tables or a
175+
data source.
176+
- **notification endpoints**: Add to notification endpoint functions.
177+
- **outputs**: Add to functions to output data to a data source.
178+
- **sample data**: Add to functions the provide sample data.
179+
- **selectors**: Add to selector functions (functions that select rows from each
180+
input table).
181+
- **single notification**: Add to functions that send a single notification.
182+
- **tests**: Add to functions that perform tests.
183+
- **transformations**: Add to transformations (functions that take a stream of
184+
tables as input and output a stream of tables).
185+
- **type-conversions**: Add to functions that change data types.
186+
187+
## Full package documentation example
188+
```js
189+
// Package pkgName provides functions that do x and y.
190+
//
191+
// ## Examples
192+
// ```
193+
// import "pkgName"
194+
//
195+
// option pkgName.foo == "bar'
196+
// ```
197+
//
198+
// introduced: 0.140.0
199+
// contributors: [@username](https://github.com/username/) (GitHub)
200+
package pkgName
201+
202+
// myFn multiplies `x` by `y`.
203+
//
204+
// ## Parameters
205+
// - x: Left operand.
206+
// - y: Right operand.
207+
//
208+
// ## Examples
209+
//
210+
// ### Multiply x and y
211+
// ```no_run
212+
// import "pkgName"
213+
//
214+
// pkgName.myFn(x: 2, y: 4)
215+
// // Returns 8
216+
// ```
217+
//
218+
myFn = (x, y) => x * y
219+
220+
// anotherFn drops columns from input tables.
221+
//
222+
// ## Parameters
223+
// - columns: List of columns to drop.
224+
// - tables: Input data. Default is piped-forward data.
225+
//
226+
// ## Examples
227+
//
228+
// ### Drop specific columns
229+
// ```
230+
// import "sampledata"
231+
// import "pkgName"
232+
//
233+
// < sampledata.float()
234+
// > |> pkgName.anotherFn(columns: [tag])
235+
// ```
236+
//
237+
// introduced: 0.141.0
238+
// tags: transformations
239+
anotherFn = (columns, tables=<-) => tables |> drop(columns: columns)
240+
```

0 commit comments

Comments
 (0)
Please sign in to comment.