-
Notifications
You must be signed in to change notification settings - Fork 57
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: make landing pages more informative (#524)
The purpose of this PR is to use a consistent style for the three landing pages [How-to guides](https://canonical-pebble.readthedocs-hosted.com/en/latest/how-to/), [Explanation](https://canonical-pebble.readthedocs-hosted.com/en/latest/explanation/), and [Reference](https://canonical-pebble.readthedocs-hosted.com/en/latest/reference/). How-to guides already has the style we want, so I'm using the same style for Explanation and Reference. Summary of changes: - **How-to guides** - Adjusted some wording for readability and consistency of language - **Explanation** - Moved [General model](https://canonical-pebble.readthedocs-hosted.com/en/latest/explanation/general-model/) to the top of the TOC; split the landing page into sections with brief summaries - **Reference** - Applied a logical order to the TOC; split the landing page into sections with brief summaries
- Loading branch information
Showing
5 changed files
with
108 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,40 @@ | ||
# Explanation | ||
|
||
These guides explain how Pebble works. | ||
|
||
|
||
## Fundamentals | ||
|
||
Pebble works as a daemon and a client, with state and configuration stored in the `$PEBBLE` directory. | ||
|
||
```{toctree} | ||
:titlesonly: | ||
:maxdepth: 1 | ||
API and clients <api-and-clients> | ||
General model <general-model> | ||
``` | ||
|
||
|
||
## Access to the API | ||
|
||
The daemon exposes an API that clients can connect to. By default, Pebble restricts access to some API endpoints based on the user that is connecting. You can set up named "identities" to grant specific access levels to users. | ||
|
||
```{toctree} | ||
:titlesonly: | ||
:maxdepth: 1 | ||
API and clients <api-and-clients> | ||
``` | ||
|
||
|
||
## Service orchestration | ||
|
||
Pebble automatically starts and stops services if you specify dependencies between services. | ||
|
||
```{toctree} | ||
:titlesonly: | ||
:maxdepth: 1 | ||
Service dependencies <service-dependencies> | ||
Service start order <service-start-order> | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,17 +1,88 @@ | ||
# Reference | ||
|
||
These guides provide technical information about Pebble. | ||
|
||
% COMMENT: This toctree is for the navigation sidebar only | ||
% Use an alphabetical listing of pages in the toctree | ||
% For each page, make sure there's also a link in a section below | ||
|
||
```{toctree} | ||
:hidden: | ||
:titlesonly: | ||
:maxdepth: 1 | ||
Changes and tasks <changes-and-tasks> | ||
CLI Commands <cli-commands/cli-commands> | ||
CLI commands <cli-commands/cli-commands> | ||
Health checks <health-checks> | ||
Identities <identities> | ||
Layers <layers> | ||
Layer specification <layer-specification> | ||
Log forwarding <log-forwarding> | ||
Notices <notices> | ||
Pebble in containers <pebble-in-containers> | ||
Service auto-restart <service-auto-restart> | ||
Use Pebble in containers <pebble-in-containers> | ||
``` | ||
|
||
|
||
% COMMENT: The first few pages are presented in a more logical reading order | ||
|
||
|
||
## Layers | ||
|
||
Pebble configuration is defined as a stack of "layers". | ||
|
||
* [Layers](layer-specification) | ||
* [Layer specification](layer-specification) | ||
|
||
|
||
## Pebble commands | ||
|
||
The `pebble` command has several subcommands. | ||
|
||
* [CLI commands](cli-commands/cli-commands) | ||
|
||
|
||
## Pebble in containers | ||
|
||
When the Pebble daemon is running inside a remote system (for example, a separate container), you can manage the remote system using subcommands on the Pebble client. | ||
|
||
* [Pebble in containers](pebble-in-containers) | ||
|
||
|
||
## Service failures | ||
|
||
Pebble provides two ways to automatically restart services when they fail. Auto-restart is based on exit codes from services. Health checks are a more sophisticated way to test and report the availability of services. | ||
|
||
* [Service auto-restart](service-auto-restart) | ||
* [Health checks](health-checks) | ||
|
||
|
||
% COMMENT: After this point, match the alphabetical listing of pages | ||
|
||
|
||
## Changes and tasks | ||
|
||
Pebble tracks system changes as "tasks" grouped into "change" objects. | ||
|
||
* [Changes and tasks](changes-and-tasks) | ||
|
||
|
||
## Identities | ||
|
||
You can set up named "identities" to control access to the API. | ||
|
||
* [Identities](identities) | ||
|
||
|
||
## Log forwarding | ||
|
||
Pebble can send service logs to a Loki server. | ||
|
||
* [Log forwarding](log-forwarding) | ||
|
||
|
||
## Notices | ||
|
||
Pebble records events as "notices". In addition to the built-in notices, clients can report custom notices. | ||
|
||
* [Notices](notices) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters