Skip to content

Commit

Permalink
docs: make landing pages more informative (#524)
Browse files Browse the repository at this point in the history
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
dwilding authored Nov 27, 2024
1 parent ce116b9 commit 2b5f306
Show file tree
Hide file tree
Showing 5 changed files with 108 additions and 8 deletions.
31 changes: 30 additions & 1 deletion docs/explanation/index.md
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>
```
6 changes: 3 additions & 3 deletions docs/how-to/index.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# How-to guides

These guides will walk you through every step of using Pebble through its complete operations lifecycle.
These guides walk you through key operations you can perform with Pebble.


## Installation

Installation follows a broadly similar pattern on all architectures, and you can choose to install the pre-built binary or build it from the source by yourself.
Installation follows a similar pattern on all architectures. You can choose to install the pre-built binary or build it from the source by yourself.

```{toctree}
:titlesonly:
Expand All @@ -29,7 +29,7 @@ Manage service dependencies <service-dependencies>

## Identities

Use named identities to allow additional users to access the API.
Use named "identities" to allow additional users to access the API.

```{toctree}
:titlesonly:
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/cli-commands/cli-commands.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# CLI Commands
# CLI commands

Pebble uses subcommands, like some other command-line tools such as go tool or git.

Expand Down
75 changes: 73 additions & 2 deletions docs/reference/index.md
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)
2 changes: 1 addition & 1 deletion docs/reference/pebble-in-containers.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Use Pebble in containers
# Pebble in containers

Pebble works well as a local service manager, but if running Pebble in a separate container, you can use the exec and file management APIs to coordinate with the remote system over the shared unix socket.

Expand Down

0 comments on commit 2b5f306

Please sign in to comment.