79747b419b
* Doc: Info about $__rate_interval for naive users <!-- Thank you for sending a pull request! Here are some tips: 1. If this is your first time, please read our contribution guide at https://github.com/grafana/grafana/blob/main/CONTRIBUTING.md 2. Ensure you include and run the appropriate tests as part of your Pull Request. 3. In a new feature or configuration option, an update to the documentation is necessary. Everything related to the documentation is under the docs folder in the root of the repository. 4. If the Pull Request is a work in progress, make use of GitHub's "Draft PR" feature and mark it as such. 5. If you can not merge your Pull Request due to a merge conflict, Rebase it. This gets it in sync with the main branch. 6. Name your PR as "<FeatureArea>: Describe your change", e.g. Alerting: Prevent race condition. If it's a fix or feature relevant for the changelog describe the user impact in the title. The PR title is used to auto-generate the changelog for issues marked with the "add to changelog" label. --> **What this PR does / why we need it**: For Prometheus newbies (i.e. most of us), it seems like $__rate_interval should be widely used, but the documentation doesn't tell us that. So I added more about why it's good, and an explicit recommendation that it can be a good default value for use if (like most of us) you don't really understand how to choose an interval. (Let me know if that's not actually the case, but that's what I took away from https://github.com/grafana/grafana/issues/21417) Also fixed a few typos in the existing doc. **Which issue(s) this PR fixes**: <!-- - Automatically closes linked issue when the Pull Request is merged. Usage: "Fixes #<issue number>", or "Fixes (paste link of issue)" --> Fixes # **Special notes for your reviewer**: * Edits based on suggestions from @beorn7 * Update docs/sources/datasources/prometheus.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> Co-authored-by: Ivana Huckova <30407135+ivanahuckova@users.noreply.github.com> Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> Co-authored-by: Ivana <ivana.huckova@gmail.com>
Building the docs locally
When you contribute to documentation, it is a good practice to build the docs on your local machine to make sure your changes appear as you expect. This README explains the process for doing that.
Requirements
Docker >= 2.1.0.3 Yarn >= 1.22.4
Build the doc site
- On the command line, first change to the docs folder:
cd docs. - Run
make docs-quick. This launches a preview of the website with the current grafana docs athttp://localhost:3002/docs/grafana/next/which will refresh automatically when changes are made to content in thesourcesdirectory.
If you have the grafana/website repo checked out in the same directory as the grafana repo, then you can run make docs-local-static to use local assets (such as images).
Content guidelines
Edit content in the sources directory.
Using relref for internal links
Use the Hugo shortcode relref any time you are linking to other internal docs pages.
Syntax is:
{{< relref "example.md" >}}
You might need to add more context for the link (containing folders and so on, folder/example.md) if Hugo says the relref is ambiguous.
Edit the side menu
The side menu is automatically build from the file structure. Use the weight front matter parameter to order pages.
Add images
Images are currently hosted in the grafana/website repo.
Deploy changes to grafana.com
When a PR is merged to main with changes in the docs/sources directory, those changes are automatically synced to the grafana/website repo and published to the staging site.
Generally, someone from marketing will publish to production each day: so as long as the sync is successful your docs edits will be published. Alternatively, you can refer to publishing to production if you'd like to do it yourself.