mirror of
https://github.com/grafana/grafana.git
synced 2025-02-20 11:48:34 -06:00
2b9d260686
This updates the mkdocs.yml source file such that the HTTP Preferences API is included in the website navigation bar and in the HTTP API overview page. This commit also refreshes the docs/README.md file with more verbose instructions for building and viewing the documentation locally. * Original issue: #5069 Document org & user preferences HTTP docs * Original PR: #5087 Closes #5193
62 lines
1.8 KiB
Markdown
62 lines
1.8 KiB
Markdown
# Building The Docs
|
|
|
|
To build the docs locally, you need to have docker installed. The
|
|
docs are built using a custom [docker](https://www.docker.com/) image
|
|
and the [mkdocs](http://www.mkdocs.org/) tool.
|
|
|
|
**Prepare the Docker Image**:
|
|
|
|
Build the `grafana/docs-base:latest` image. Run these commands in the
|
|
same directory this file is in. **Note** that you may require ``sudo``
|
|
when running ``make docs-build`` depending on how your system's docker
|
|
service is configured):
|
|
|
|
```
|
|
$ git clone https://github.com/grafana/docs-base
|
|
$ cd docs-base
|
|
$ make docs-build
|
|
```
|
|
|
|
**Build the Documentation**:
|
|
|
|
Now that the docker image has been prepared we can build the
|
|
docs. Switch your working directory back to the directory this file
|
|
(README.md) is in and run (possibly with ``sudo``):
|
|
|
|
```
|
|
$ make docs
|
|
```
|
|
|
|
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
|
|
we created in the previous step.
|
|
|
|
Open [localhost:8180](http://localhost:8180) to view the docs.
|
|
|
|
**Note** that after running ``make docs`` you may notice a message
|
|
like this in the console output
|
|
|
|
> Running at: http://0.0.0.0:8000/
|
|
|
|
This is misleading. That is **not** the port the documentation is
|
|
served from. You must browse to port **8180** to view the new
|
|
documentation.
|
|
|
|
|
|
# Adding a New Page
|
|
|
|
Adding a new page requires updating the ``mkdocs.yml`` file which is
|
|
located in this directory.
|
|
|
|
For example, if you are adding documentation for a new HTTP API called
|
|
``preferences`` you would:
|
|
|
|
1. Create the file ``docs/sources/http_api/preferences.md``
|
|
1. Add a reference to it in ``docs/sources/http_api/overview.md``
|
|
1. Update the list under the **pages** key in the ``docs/mkdocs.yml`` file with a reference to your new page:
|
|
|
|
|
|
```yaml
|
|
- ['http_api/preferences.md', 'API', 'Preferences API']
|
|
```
|