Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

restructured readme and contribution guidelines

pull/3/head
Scott Anderson 2019-01-09 16:08:51 -07:00
parent 76cf532798
commit 84a03c680a
2 changed files with 255 additions and 247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

251
CONTRIBUTING.md
View File

@ -1,19 +1,242 @@
# Contributing to InfluxData Documentation # Contributing to InfluxData Documentation
We welcome (and encourage!) contributions from the community. ## Sign the InfluxData CLA
The InfluxData Contributor License Agreement (CLA) is part of the legal framework
for the open-source ecosystem that protects both you and InfluxData.
In order to contribute to any InfluxData project, you must first sign the CLA.
- Sign the [InfluxData Contributor License Agreement (CLA)](https://www.influxdata.com/legal/cla/). [Sign the InfluxData (CLA)](https://www.influxdata.com/legal/cla/)
- [Downlaod and install Hugo](http://gohugo.io/overview/installing/). ## Make suggested updates
- Fork this repository on GitHub.
- Clone the repo to your local computer.
```bash ### Fork and clone InfluxData Documentation Repository
git clone https://github.com/your_username/docs.influxdata.com.git [Fork this repository](https://help.github.com/articles/fork-a-repo/) and
cd docs.influxdata.com/ [clone it](https://help.github.com/articles/cloning-a-repository/) to your local machine.
```
- Make your changes. ### Run the documentation locally (optional)
- Make sure the site compiles locally with `hugo server --watch`. To run the documentation locally, follow the instructions provided in the README.
- Check it out at [localhost:1313](http://localhost:1313/).
- Submit a pull request. ### Make your changes
- Earn the respect, admiration, and eternal love of the entire InfluxData community. Make your suggested changes being sure to follow the [style and formatting guidelines](#style--formatting) outline below.
### Submit a pull request
Push your changes up to your forked repository, then [create a new pull request](https://help.github.com/articles/creating-a-pull-request/).
## Style & Formatting
### Markdown
All of our documentation is written in [Markdown](https://en.wikipedia.org/wiki/Markdown).
### Semantic Linefeeds
Use [semantic linefeeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/).
Separating each sentence with a new line makes it easy to parse diffs with the human eye.
**Diff without semantic linefeeds:**
``` diff
-Data are taking off. Those data are time series. You need a database that specializes in time series. You should check out InfluxDB.
+Data are taking off. Those data are time series. You need a database that specializes in time series. You need InfluxDB.
```
**Diff with semantic linefeeds:**
``` diff
Data are taking off.
Those data are time series.
You need a database that specializes in time series.
-You should check out InfluxDB.
+You need InfluxDB.
```
### Page frontmatter
Every documentation page includes frontmatter which specifies information about the page.
Frontmatter populates variables in page templates and the site's navigation menu.
```yaml
title: # Title of the page used in the the page's h1
seotitle: # Page title used in the html <head> title and used in search engine results
description: # Page description displayed in search engine results
menu:
v2_0:
name: # Article name that only appears in the left nav
parent: # Specifies a parent group and nests navigation items
weight: # Determines sort order.
draft: # If true, will not render page on build
enterprise_all: # If true, specifies the doc as a whole is specific to InfluxDB Enterprise
enterprise_some: # If true, specifies the doc includes some content specific to InfluxDB Enterprise
```
#### Title usage
##### `title`
The `title` frontmatter populates each page's h1 header.
It shouldn't be overly long, but should set the context for users coming from outside sources.
##### `seotitle`
The `seotitle` frontmatter populates each page's HTML `title` attribute.
Search engines use this in search results (not the page's h1) and therefore it should be keyword optimized.
##### `menu > name`
The `name` attribute under the `menu` frontmatter determines the text used in each page's link in the site navigation.
It should be short and assume the context of its parent if it has one.
### Article headings
Use only h2-h6 headings in markdown content.
h1 headings act as the page title and are populated automatically from the `title` frontmatter.
h2-h6 headings act as section headings.
### Notes and warnings
Shortcodes are available for formatting notes and warnings in each article:
```md
{{% note %}}
Insert note markdown content here.
{{% /note %}}
{{% warn %}}
Insert warning markdown content here.
{{% /warn %}}
```
### Enterprise Content
Many articles are unique to InfluxDB enterprise or at least contain some information specific to InfluxDB Enterprise.
There are frontmatter options and an enterprise shortcode that help to properly identify this content.
#### All content is Enterprise-specific
If all content in an article is Enterprise-specific, set the `enterprise_all` frontmatter to `true`.
```yaml
enterprise_all: true
```
This will display a message at the top of page indicating that the things discussed are unique to InfluxDB Enterprise.
#### Only some content is Enterprise-specific
If only some content in the article is enterprise specific, set the `enterprise_some` frontmatter to `true`.
```yaml
enterprise_some: true
```
This will display a message at the top of page indicating some things are unique to InfluxDB Enterprise.
To format Enterprise-specific content, wrap it in the `{{% enterprise %}}` shortcode:
```md
{{% enterprise %}}
Insert enterprise-specific markdown content here.
{{% /enterprise %}}
```
### Tabbed Content
Shortcodes are available for creating "tabbed" content (content that is changed by a users' selection).
Ther following three must be used:
`{{< tabs-wrapper >}}`
This shortcode creates a wrapper or container for the tabbed content.
All UI interactions are limited to the scope of each container.
If you have more than one "group" of tabbed content in a page, each needs its own `tabs-wrapper`.
This shortcode must be closed with `{{< /tabs-wrapper >}}`.
**Note**: The `<` and `>` characters used in this shortcode indicate that the contents should be processed as HTML.
`{{% tabs %}}`
This shortcode creates a container for buttons that control the display of tabbed content.
It should contain simple markdown links with anonymous anchors (`#`).
The link text is used as the button text.
This shortcode must be closed with `{{% /tabs %}}`.
**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown.
`{{% tab-content %}}`
This shortcode creates a container for a content block.
Each content block in the tab group needs to be wrapped in this shortcode.
**The number of `tab-content` blocks must match the number of links provided in the `tabs` shortcode**
This shortcode must be closed with `{{% /tab-content %}}`.
**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown.
#### Example tabbed content group
```md
{{< tabs-wrapper >}}
{{% tabs %}}
[Button text for tab 1](#)
[Button text for tab 2](#)
{{% /tabs %}}
{{% tab-content %}}
Markdown content for tab 1.
{{% /tab-content %}}
{{% tab-content %}}
Markdown content for tab 2.
{{% /tab-content %}}
{{< /tabs-wrapper >}}
```
#### Tabbed code blocks
Shortcodes are also available for tabbed code blocks primarily used to give users
the option to choose between different languages and syntax.
The shortcode structure is the same as above, but the shortcode names are different:
`{{< code-tabs-wrapper >}}`
`{{% code-tabs %}}`
`{{% code-tab-content %}}`
~~~md
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Flux](#)
[InfluxQL](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```js
data = from(bucket: "telegraf/autogen")
|> range(start: -15m)
|> filter(fn: (r) =>
r._measurement == "mem" AND
r._field == "used_percent"
)
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```sql
SELECT "used_percent"
FROM "telegraf"."autogen"."mem"
WHERE time > now() - 15m
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
~~~
### High-resolution images
In many cases, screenshots included in the docs are taken from high-resolution (retina) screens.
Because of this, the actual pixel dimension is 2x larger than it needs to be and is rendered 2x bigger than it should be.
The following shortcode automatically sets a fixed width on the image using half of its actual pixel dimension.
This preserves the detail of the image and renders it at a size where there should be little to no "blur"
cause by browser image resizing.
```html
{{< img-hd src="/path/to/image" alt="Alternate title" />}}
```
###### Notes
- This should only be used on screenshots takes from high-resolution screens.
- The `src` should be relative to the `static` directory.
- Image widths are limited to the width of the article content container and will scale accordingly,
even with the `width` explicitly set.
### Truncated content blocks
In some cases, it may be appropriate to shorten or truncate blocks of content.
Use cases include long examples of output data or tall images.
The following shortcode truncates blocks of content and allows users to opt into
to seeing the full content block.
```md
{{% truncate %}}
Truncated markdown content here.
{{% /truncate %}}
```

251
README.md
View File

@ -1,28 +1,35 @@
# InfluxDB v2.0 Documentation # InfluxDB v2.0 Documentation
This is the repository represents the InfluxDB v2.x documentation that will be This is the repository contains the InfluxDB v2.x documentation that will be
accessible at [docs.influxdata.com](https://docs.influxdata.com). accessible at [docs.influxdata.com](https://docs.influxdata.com).
## Contributing
We welcome and encourage community contributions to the InfluxData See our [Contribution guidelines](blob/master/CONTRIBUTING.md) for information
about contributing to the InfluxData documentation.
## Run the docs locally ## Run the docs locally
The InfluxData documentation uses [Hugo](https://gohugo.io/), a static site
generator built in Go.
### Clone this repository
[Clone this repository](https://help.github.com/articles/cloning-a-repository/)
to your local machine.
### Install Hugo ### Install Hugo
Hugo is the static site generator used to build the InfluxData documentation. See the Hugo documentation for information about how to
[Download and install Hugo](https://gohugo.io/getting-started/installing/) to run the docs locally. [download and install Hugo](https://gohugo.io/getting-started/installing/).
### Install NodeJS & Asset Pipeline Tools ### Install NodeJS & Asset Pipeline Tools
This project uses tools built in NodeJS to build and process stylesheets and javascript. This project uses tools written in NodeJS to build and process stylesheets and javascript.
In order for the asset pipeline to work, [install NodeJS](https://nodejs.org/en/download/) In order for assets to build correctly, [install NodeJS](https://nodejs.org/en/download/)
and run the following to install the necessary tools: and run the following command to install the necessary tools:
```sh ```sh
npm i -g postcss-cli autoprefixer npm i -g postcss-cli autoprefixer
``` ```
### Fork and clone the docs repository
[Fork this repository](https://help.github.com/articles/fork-a-repo/) and [clone it](https://help.github.com/articles/cloning-a-repository/) to your local machine.
### Start the hugo server ### Start the hugo server
Hugo provides a local development server that generates the HTML pages and serves them Hugo provides a local development server that generates the HTML pages, builds
at `localhost:1313`. the static assets, and serves them at `localhost:1313`.
Start the hugo server with: Start the hugo server with:
@ -31,225 +38,3 @@ hugo server
``` ```
View the docs at [localhost:1313](http://localhost:1313). View the docs at [localhost:1313](http://localhost:1313).
## Contributing
See our [Contribution guidelines](blob/master/CONTRIBUTING.md) for information
about contributing to the InfluxData documentation.
## Style & Formatting
### Markdown
All of our documentation is written in [Markdown](https://en.wikipedia.org/wiki/Markdown).
### Semantic Linefeeds
Use [semantic linefeeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/).
Separating each sentence with a new line makes it easy to parse diffs with the human eye.
**Diff without semantic linefeeds:**
``` diff
-Data are taking off. Those data are time series. You need a database that specializes in time series. You should check out InfluxDB.
+Data are taking off. Those data are time series. You need a database that specializes in time series. You need InfluxDB.
```
**Diff with semantic linefeeds:**
``` diff
Data are taking off.
Those data are time series.
You need a database that specializes in time series.
-You should check out InfluxDB.
+You need InfluxDB.
```
### Page frontmatter
Every documentation page includes frontmatter which specifies information about the page.
Frontmatter populates variables in page templates and the site's navigation menu.
```yaml
title: # Title of the page used in the the page's h1
seotitle: # Page title used in the html <head> title and used in search engine results
description: # Page description displayed in search engine results
menu:
v2_0:
name: # Article name that only appears in the left nav
parent: # Specifies a parent group and nests navigation items
weight: # Determines sort order.
draft: # If true, will not render page on build
enterprise_all: # If true, specifies the doc as a whole is specific to InfluxDB Enterprise
enterprise_some: # If true, specifies the doc includes some content specific to InfluxDB Enterprise
```
#### Title usage
##### `title`
The `title` frontmatter populates each page's h1 header.
It shouldn't be overly long, but should set the context for users coming from outside sources.
##### `seotitle`
The `seotitle` frontmatter populates each page's HTML `title` attribute.
Search engines use this in search results (not the page's h1) and therefore it should be keyword optimized.
##### `menu > name`
The `name` attribute under the `menu` frontmatter determines the text used in each page's link in the site navigation.
It should be short and assume the context of its parent if it has one.
### Article headings
Use only h2-h6 headings in markdown content.
h1 headings act as the page title and are populated automatically from the `title` frontmatter.
h2-h6 headings act as section headings.
### Notes and warnings
Shortcodes are available for formatting notes and warnings in each article:
```md
{{% note %}}
Insert note markdown content here.
{{% /note %}}
{{% warn %}}
Insert warning markdown content here.
{{% /warn %}}
```
### Enterprise Content
Many articles are unique to InfluxDB enterprise or at least contain some information specific to InfluxDB Enterprise.
There are frontmatter and an enterprise shortcode that help to properly identify this content.
#### All content is Enterprise-specific
If all content in an article is Enterprise-specific, set the `enterprise_all` frontmatter to `true`.
```yaml
enterprise_all: true
```
This will display a message at the top of page indicating that the things discussed are unique to InfluxDB Enterprise.
#### Only some content is Enterprise-specific
If only some content in the article is enterprise specific, set the `enterprise_some` frontmatter to `true`.
```yaml
enterprise_some: true
```
This will display a message at the top of page indicating some things are unique to InfluxDB Enterprise.
To format Enterprise-specific content, wrap it in the `{{% enterprise %}}` shortcode:
```md
{{% enterprise %}}
Insert enterprise-specific markdown content here.
{{% /enterprise %}}
```
### Tabbed Content
Shortcodes are available for creating "tabbed" content (content that is changed by a users' selection).
Ther following three must be used:
`{{< tabs-wrapper >}}`
This shortcode creates a wrapper or container for the tabbed content.
All UI interactions are limited to the scope of each container.
If you have more than one "group" of tabbed content in a page, each needs its own `tabs-wrapper`.
This shortcode must be closed with `{{< /tabs-wrapper >}}`.
**Note**: The `<` and `>` characters used in this shortcode indicate that the contents should be processed as HTML.
`{{% tabs %}}`
This shortcode creates a container for buttons that control the display of tabbed content.
It should contain simple markdown links with anonymous anchors (`#`).
The link text is used as the button text.
This shortcode must be closed with `{{% /tabs %}}`.
**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown.
`{{% tab-content %}}`
This shortcode creates a container for a content block.
Each content block in the tab group needs to be wrapped in this shortcode.
**The number of `tab-content` blocks must match the number of links provided in the `tabs` shortcode**
This shortcode must be closed with `{{% /tab-content %}}`.
**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown.
#### Example tabbed content group
```md
{{< tabs-wrapper >}}
{{% tabs %}}
[Button text for tab 1](#)
[Button text for tab 2](#)
{{% /tabs %}}
{{% tab-content %}}
Markdown content for tab 1.
{{% /tab-content %}}
{{% tab-content %}}
Markdown content for tab 2.
{{% /tab-content %}}
{{< /tabs-wrapper >}}
```
#### Tabbed code blocks
Shortcodes are also available for tabbed code blocks primarily used to give users
the option to choose between different languages and syntax.
The shortcode structure is the same as above, but the shortcode names are different:
`{{< code-tabs-wrapper >}}`
`{{% code-tabs %}}`
`{{% code-tab-content %}}`
~~~md
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Flux](#)
[InfluxQL](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```js
data = from(bucket: "telegraf/autogen")
|> range(start: -15m)
|> filter(fn: (r) =>
r._measurement == "mem" AND
r._field == "used_percent"
)
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```sql
SELECT "used_percent"
FROM "telegraf"."autogen"."mem"
WHERE time > now() - 15m
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
~~~
### High-resolution images
In many cases, screenshots included in the docs are taken from high-resolution (retina) screens.
Because of this, the actual pixel dimension is 2x larger than it needs to be and is rendered 2x bigger than it should be.
The following shortcode automatically sets a fixed width on the image using half of its actual pixel dimension.
This preserves the detail of the image and renders it at a size where there should be little to no "blur"
cause by browser image resizing.
```html
{{< img-hd src="/path/to/image" alt="Alternate title" />}}
```
###### Notes
- This should only be used on screenshots takes from high-resolution screens.
- The `src` should be relative to the `static` directory.
- Image widths are limited to the width of the article content container and will scale accordingly,
even with the `width` explicitly set.
### Truncated content blocks
In some cases, it may be appropriate to shorten or truncate blocks of content.
Use cases include long examples of output data or tall images.
The following shortcode truncates blocks of content and allows users to opt into
to seeing the full content block.
```md
{{% truncate %}}
Truncated markdown content here.
{{% /truncate %}}