Skip to content

Commit

Permalink
Declutter & restructure README
Browse files Browse the repository at this point in the history 
Signed-off-by: Vipul Gupta (@vipulgupta2048) <vipul@balena.io>
  • Loading branch information
@vipulgupta2048
vipulgupta2048 committed Apr 2, 2021
1 parent 66a421a commit b4bee77
Showing 1 changed file with 65 additions and 70 deletions.
135 changes: 65 additions & 70 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,100 +1,107 @@
Balena Documentation
======================
# balenaCloud Documentation

Documentation for the [balenaCloud](https://balena.io/) platform. Join our [forums](https://forums.balena.io/) to chat.
![GitHub tag](https://img.shields.io/github/v/tag/balena-io/docs)![GitHub issues](https://img.shields.io/github/issues/balena-io/docs) ![GitHub License](https://img.shields.io/github/license/balena-io/docs)

Role
----
Documentation for the [balenaCloud](https://balena.io/) platform lives here.
Join our [forums](https://forums.balena.io/) to chat.

The intention of this repo is to provide our public-facing documentation. To view the documentation generated by this repo you should either [run locally](#running-locally) or view the [hosted version](https://www.balena.io/docs/).
## Role

Running locally
---------------
The intention of this repo is to provide our public-facing documentation. To view the documentation generated by this repo, one could either [run locally](#getting-started) or view the [hosted version](https://www.balena.io/docs/).

To run the docs web application locally, you should do the following:
## How to Contribute

```sh
git clone https://github.com/balena-io/docs
If you think a part is not documented, outdated or can be improved on the [website](https://docs.balena.io), don't hesitate in sending a PR! Check our [CONTRIBUTING document](CONTRIBUTING.md) for the guidelines to ensure your PR can be merged as quickly as possible.
One can open or check existing issues on [GitHub issues](https://github.com/balena-io/docs/issues). Looking forward to see your contributions!

> Pro tip: Use the "Improve This Doc" button to identify the right file on the GitHub repository.
![Improve-this-doc-button](https://user-images.githubusercontent.com/22801822/113413629-babb7b00-93d8-11eb-92c2-7cca35b2029d.png)

## Getting Started

```bash
git clone https://github.com/balena-io/docs.git
cd docs
npm install
npm run build
```

Now to check that everything is working correctly, start the local server with:

```
npm start
```
And then open [http://localhost:3000/docs](http://localhost:3000/docs).

You should now see the docs served from [http://localhost:3000/docs](http://localhost:3000/docs) running locally on your device. This helps in iterating quickly while making changes and seeing the preview of every change.

> Note: if you are using macOS and you get `"RangeError: Maximum call stack size exceeded"`
> when running `npm install` (which eventually calls the `build.sh` script), have a look at
> the comments at the top of the `'Dockerfile.bindmount'` file.
To add you changes to the docs, create a new local branch of master:

How to Contribute
----------
```
git checkout -b my-docs-patch
```

- Issue Tracker: [github.com/balena-io/docs/issues](https://github.com/balena-io/docs/issues)
- Source Code: [github.com/balena-io/docs](https://github.com/balena-io/docs)
Now you can make changes in this branch. Since our docs are static pages generated from markdown using metalsmith.io, each time you change some of the `.md` files you will need to run rebuild of the docs to generate the static pages. This is done by running:

If you think something is not documented, or can be improved, don't hesitate in sending a PR! Check [CONTRIBUTING.md](CONTRIBUTING.md) for the guidelines to ensure your PR can be merged as quickly as possible.
```
npm run build:fast
```

This will skip over downloading files from external sources which takes a while. However there is a handy watch functionality that will watch for changes in `/pages`, `/shared`, and `/templates` and rebuild each time you save your changes. To use this, open a new tab in your terminal and run:

```
npm run watch-pages
```

Deploying
----------
Once you are happy with your changes, submit a pull request for you branch against `master`. Make sure to read the [CONTRIBUTING document](CONTRIBUTING.md).

After a PR has been created, a member of the balena team will review and merge into `staging`.
_Note_ that you have to restart the development server if you edit other things like `redirects.txt`.

Shortly after merging to `staging` it'll automatically be deployed to our [staging environment](https://www.balena-staging.io/docs/) (This should only take a few minutes).
## Deploying

Once deployed to staging, we will preview your changes. If everything looks good, a member of the balena team will make another PR from `staging` into the `master` branch. When this is merged, the changes will automatically deploy to [production](https://balena.io/docs)
After a PR has been created, a member of the balena team will review and merge the PR. The pull request will undergo CI/CD checks to verify if everything is correct. For example: if a Change-type has been added. More information present in the [CONTRIBUTING document](CONTRIBUTING.md)

Shortly after merging the PR to the `master` branch, it'll automatically be deployed to our [production environment](https://www.balena.io/docs/) (This should only take a few minutes).

Style manual
----------
If the feature/change needs to be previewed, a member of the balena team can/will deploy the PR to staging to check the changes. If everything looks good, then the PR would be merged into the into the `master` branch.

### Default style manual: (TBD)
## Style manual

### Balena-specific words
For all, lower-case capitalization unless beginning a sentence (Ex. *I like balena. Balena is great.*)

For all instances, we use `balena` as lower-case capitalization unless beginning a sentence (Ex. *I like balena. Balena is great.*). More instances as follows, \

* **balena** (used to refer to the company as a whole, not in place of balenaCloud, balenaOS or any other project)
* **balenaEtcher**
* **balenaOS** (note the capitalization of **OS**)
* **balenaEngine**
* **balenaFin**
* **balenaCloud**
* the **balena CLI**
* the **balena Supervisor**
* **openbalena**

### Conventions & Best Practices

Conventions
-----------
- Notes/Warnings are formatted using CSS. Use the following syntax to make sure it's rendered correctly: `__Note:__`

### Get Setup
- It's important to note that `h1` and `h2` headings will automatically be included in the left hand side navigation bar, so make sure to use these appropriately and sparingly.

```sh
git clone https://github.com/balena-io/docs.git
cd docs
npm install
npm run build
```
Now to check that everything is working correctly, start the local server with:
```
npm start
```
You should now see the docs served from [http://localhost:3000/docs](http://localhost:3000/docs)
- We also use simple modules, to easily interpolate strings, reuse variables, and maintain consistency all across the documentation for our naming convention.

Names module can be found [here](https://github.com/balena-io/docs/blob/master/config/names.coffee) with references to specific names being used across the documentation. These references can be used inside the documentation files using fluid tags like the example below.

To add you changes to the docs, create a new local branch of master:
```
git checkout -b my-docs-patch
```
Now you can make changes in this branch. Since our docs are static pages generated from markdown using metalsmith.io, each time you change some of the `.md` files you will need to run rebuild of the docs to generate the static pages. This is done by running:
```
npm run build:fast
```
This will skip over downloading files from external sources which takes a while. However there is a handy watch functionality that will watch for changes in `/pages`, `/shared`, and `/templates` and rebuild each time you save your changes. To use this, open a new tab in your terminal and run:
```
npm run watch-pages
```
Once you are happy with your changes, submit a pull request for you branch against `master`.
Deploy with {{ $names.company.lower }}
{{ $names.os.lower }} image configured
Select the {{ $device.name }} device type
_Note_ that you have to restart the development server if you edit other things like `redirects.txt`.
[multicontainer-project]:{{ $links.githubLabs }}/multicontainer-getting-started/tree/master/haproxy
```

### Using Partials

Expand All @@ -116,30 +123,18 @@ To use these partials in a markdown page all you need to do is add the following
```
and the engine will pull that partial into this location in the page.

### Adding external documentation

To add additional external documentation follow these steps:

1. Update `tools/fetch-external.sh` to add the additional external source. If required rename the source document as this will be used in the docs URL and in dynamically determining the "Improve this doc" link and must be unique.
2. Update `externalDocs` in `config/links.coffee` to add the link to edit the source file. This is the link presented in "Improve this doc". The key must match the name of the filename without the .md extension e.g. `"node-sdk": 'https://github.com/balena-io/balena-sdk/edit/master/DOCUMENTATION.md'` for a file named `node-sdk.md`.
3. In `config/index.coffee` add the filename (again without the .md extension) to the `EXTERNAL_DOCS` variable so that the system knows to correctly identify this file as coming from an external source.
4. If the source is currently duplicated in this repo then delete the content from this repo and add the file to `/.gitignore`.

### Some other important bits

Its important to note that `h1` and `h2` headings will automatically be included in the left hand side navigation bar, so make sure to use these appropriately.
In the dynamically generated pages (the ones with the device-type and language dropdown) it is possible to use templates to dynamically change the device name and language name in your text.

Here is an example:

In the dynamically generated pages (the ones with the device-type and language dropdown) it is possible to use templates to dynamically change the device name and language name in your text. Here is an example:
```
Getting started with {{ $device_details.name }} using {{ $language_details.name }}
```
To add additional dynamic properties, see the files in `/config/dictionaries`.

If you remove a page that may be linked to externally to the docs, remember to add it to the `redirects.txt` in the root of the docs, if you don’t, then links will break and people will have a bad time, m’kay.

If you need to add image assets, add them to the `/static/img` folder, either under common if these images are general to all of the devices or balena, otherwise add them to the specific device folder.
To add additional dynamic properties, see the files in `/config/dictionaries`.

License
-------
## License

The project is licensed under the Apache 2.0 license.

0 comments on commit b4bee77

Please sign in to comment.