public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Improve guides for contributing (#19575)

Browse Source 
* Move style guides into contribute directory

* Move contribution guides into contribute directory

* Refactor CONTRIBUTING.md

* Clean up docs/README.md

* Update reference to style guide and minor formatting fixes

* Apply suggestions from code review

Co-Authored-By: gotjosh <josue.abreu@gmail.com>

* Update CONTRIBUTING.md

Co-Authored-By: gotjosh <josue.abreu@gmail.com>
This commit is contained in:
Marcus Olsson
2019-10-03 14:13:58 +02:00
committed by GitHub
co-authored by gotjosh
parent 27ddd2d60f
commit 2fb301ccaf
14 changed files with 189 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+17 -16
View File
@@ -6,14 +6,14 @@ The Markdown content however, is still public in this repository. We still encou
# Building the docs
To build the docs locally, you need to have docker installed. The docs are built using [Hugo](http://gohugo.io/) - a static site generator.
To build the docs locally, you need to have Docker installed. The docs are built using [Hugo](http://gohugo.io/) - a static site generator.
**Prepare the Docker Image**:
**Prepare the Docker image**:
> Due to migration to new static site, the docker image needs to be built from `old-docs` branch.
> Due to migration to new static site, the Docker image needs to be built from `old-docs` branch.
Git clone `grafana/website` repo. Run these commands in the root of that repo. **Note** that you may require ``sudo``
when running ``make docs-build`` depending on how your system's docker
Git clone `grafana/website` repo. Run these commands in the root of that repo. **Note** that you may require `sudo`
when running `make docs-build` depending on how your system's Docker
service is configured):
```
@@ -24,7 +24,7 @@ make docs-build
**Build the Documentation**:
Now that the docker image has been prepared we can build the
Now that the Docker image has been prepared we can build the
grafana docs and start a docs server.
If you have not cloned the Grafana repository already then:
@@ -47,14 +47,14 @@ An AWS config file is required to build the docs Docker image and to publish the
touch awsconfig
```
Then run (possibly with ``sudo``):
Then run (possibly with `sudo`):
```
make watch
```
This command will not return control of the shell to the user. Instead
the command is now running a new docker container built from the image
the command is now running a new Docker container built from the image
we created in the previous step.
Open [localhost:3004](http://localhost:3004) to view the docs.
@@ -63,20 +63,21 @@ Open [localhost:3004](http://localhost:3004) to view the docs.
All markdown files are part of [this repository](https://github.com/grafana/grafana). However, all images are added to the [website repository](https://github.com/grafana/website). Therefore, the process of adding images is not as straightforward. These are the steps:
1. Ensure you create a feature branch within the [website repository](https://github.com/grafana/website) to make the change. This branch needs to be based on the `old-docs` branch.
2. Ensure the image(s) are compressed and optimised e.g. Using [tinypng](https://tinypng.com/)
2. Add the image(s) to the `/static/img/docs` directory
3. Then, make a commit that adds the image(s)
4. The Pull Request you create needs to target where you branched off, the branch `old-docs`
1. Ensure you create a feature branch within the [website repository](https://github.com/grafana/website) to make the change. This branch needs to be based on the `old-docs` branch.
1. Ensure the image(s) are compressed and optimised e.g. Using [tinypng](https://tinypng.com/).
1. Add the image(s) to the `/static/img/docs` directory.
1. Then, make a commit that adds the image(s).
1. The Pull Request you create needs to target where you branched off, the branch `old-docs`.
Finally, run:
```
make docs-build
```
This will rebuild the docs docker image.
This will rebuild the docs Docker image.
To be able to use your image(s) you have to quit (CTRL-C) the `make watch` command (that you run in the same directory as this README). Then simply rerun `make watch`, it will restart the docs server but now with access to your image(s).
To be able to use your image(s) you have to quit (CTRL-C) the `make watch` command (that you run in the same directory as this README). Then simply rerun `make watch`, it will restart the docs server but now with access to your image(s).
### Editing content
@@ -86,4 +87,4 @@ Changes to the markdown files should automatically cause a docs rebuild and live
#### Running `make watch` errors out with `Warning: Task "default" not found.`
Ensure that the docker image from the [website repository](https://github.com/grafana/website) is built using the `old-docs` branch.
Ensure that the Docker image from the [website repository](https://github.com/grafana/website) is built using the `old-docs` branch.