Skip to content

Commit 6c6091a

Browse files
DimCitusDimCitus
authored
Add individual pages for the pg_autoctl commands. (#632)
* Add individual pages for the pg_autoctl commands, first pass. * Update readthedocs badge. * Review table-of-contents and man pages organisation. * Revert accidental file format change. * Current organisation requires maxdepth 4. * Fix ReST source format for options lists in manual pages. * Finish manual pages coverage of the pg_autoctl show commands. * Manual page coverage for pg_autoctl drop commands. * Manual pages coverage for pg_autoctl config commands. * Update man pages conf, assorted fixes. * Fix reload for pg_autoctl config set documentation. * Manual pages coverage for pg_autoctl "service" commands. * Manual pages coverage for pg_autoctl enable|disable commands. * Assorted fixes. * Manual pages for pg_autoctl get|set commands. * Manual pages coverage for pg_autoctl perform commands. * Fix man pages setup. * More manual pages coverage, removal of the old reference text. * Add some more coverage for pg_autoctl do subcommands. We limit ourselves to those commands which might be useful for the users, and the pg_autoctl do show and pg_autoctl do pgsetup commands seem to fall right in that bag. * Fix pg_autoctl show uri. * Fix list of manual pages. * Improve pg_autoctl do main page. * Manual pages coverage for pg_autoctl enable|disable monitor. * Improvements to some pages. * Fix latex document production (no support for braille unicode chars). * Fix pg_autoctl show ... commands option help string. * Fix pg_autoctl show state when the monitor is disabled. * Fix pg_autoctl show state --group when group is wrong. * Fix pg_autoctl get formation ... when target formation doesn't exists. * Fix pg_autoctl show state --pgdata monitor. * Per review.
1 parent 78132d1 commit 6c6091a

66 files changed

Lines changed: 4589 additions & 1091 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Makefile‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,8 +162,10 @@ pdf: $(PDF)
162162
$(PDF):
163163
$(MAKE) -s -C docs/tikz pdf
164164
perl -pi -e 's/(^.. figure:: .*)\.svg/\1.pdf/' docs/*.rst
165+
perl -pi -e 's/▒/~/g' docs/ref/pg_autoctl_do_demo.rst
165166
$(MAKE) -s -C docs latexpdf
166167
perl -pi -e 's/(^.. figure:: .*)\.pdf/\1.svg/' docs/*.rst
168+
perl -pi -e 's/~/▒/g' docs/ref/pg_autoctl_do_demo.rst
167169
ls -l $@
168170

169171
$(FSM): bin

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# pg_auto_failover
22

33
[![Slack Status](http://slack.citusdata.com/badge.svg)](https://slack.citusdata.com)
4-
[![Documentation Status](https://readthedocs.org/projects/pg-auto-failover/badge/?version=latest)](https://pg-auto-failover.readthedocs.io/en/latest/?badge=latest)
4+
[![Documentation Status](https://readthedocs.org/projects/pg-auto-failover/badge/?version=latest)](https://pg-auto-failover.readthedocs.io/en/master/?badge=master)
55

66
pg_auto_failover is an extension and service for PostgreSQL that monitors
77
and manages automated failover for a Postgres cluster. It is optimized for

‎docs/conf.py‎

Lines changed: 261 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,267 @@ def __init__(self, **options):
171171
[author],
172172
1,
173173
),
174-
("ref/reference", "pg_autoctl", "pg_auto_failover agent", [author], 1),
174+
("ref/pg_autoctl", "pg_autoctl", "pg_autoctl", [author], 1),
175+
(
176+
"ref/pg_autoctl_create_monitor",
177+
"pg_autoctl create monitor",
178+
"pg_autoctl create monitor",
179+
[author],
180+
1,
181+
),
182+
(
183+
"ref/pg_autoctl_create_postgres",
184+
"pg_autoctl create postgres",
185+
"pg_autoctl create postgres",
186+
[author],
187+
1,
188+
),
189+
(
190+
"ref/pg_autoctl_create_formation",
191+
"pg_autoctl create formation",
192+
"pg_autoctl create formation",
193+
[author],
194+
1,
195+
),
196+
(
197+
"ref/pg_autoctl_drop_monitor",
198+
"pg_autoctl drop monitor",
199+
"pg_autoctl drop monitor",
200+
[author],
201+
1,
202+
),
203+
(
204+
"ref/pg_autoctl_drop_node",
205+
"pg_autoctl drop node",
206+
"pg_autoctl drop node",
207+
[author],
208+
1,
209+
),
210+
(
211+
"ref/pg_autoctl_drop_formation",
212+
"pg_autoctl drop formation",
213+
"pg_autoctl drop formation",
214+
[author],
215+
1,
216+
),
217+
(
218+
"ref/pg_autoctl_config_get",
219+
"pg_autoctl config get",
220+
"pg_autoctl config get",
221+
[author],
222+
1,
223+
),
224+
(
225+
"ref/pg_autoctl_config_set",
226+
"pg_autoctl config set",
227+
"pg_autoctl config set",
228+
[author],
229+
1,
230+
),
231+
(
232+
"ref/pg_autoctl_config_check",
233+
"pg_autoctl config check",
234+
"pg_autoctl config check",
235+
[author],
236+
1,
237+
),
238+
(
239+
"ref/pg_autoctl_show_uri",
240+
"pg_autoctl show uri",
241+
"pg_autoctl show uri",
242+
[author],
243+
1,
244+
),
245+
(
246+
"ref/pg_autoctl_show_events",
247+
"pg_autoctl show events",
248+
"pg_autoctl show events",
249+
[author],
250+
1,
251+
),
252+
(
253+
"ref/pg_autoctl_show_state",
254+
"pg_autoctl show state",
255+
"pg_autoctl show state",
256+
[author],
257+
1,
258+
),
259+
(
260+
"ref/pg_autoctl_show_file",
261+
"pg_autoctl show file",
262+
"pg_autoctl show file",
263+
[author],
264+
1,
265+
),
266+
(
267+
"ref/pg_autoctl_show_settings",
268+
"pg_autoctl show settings",
269+
"pg_autoctl show settings",
270+
[author],
271+
1,
272+
),
273+
(
274+
"ref/pg_autoctl_show_standby_names",
275+
"pg_autoctl show standby-names",
276+
"pg_autoctl show standby-names",
277+
[author],
278+
1,
279+
),
280+
(
281+
"ref/pg_autoctl_enable_maintenance",
282+
"pg_autoctl enable maintenance",
283+
"pg_autoctl enable maintenance",
284+
[author],
285+
1,
286+
),
287+
(
288+
"ref/pg_autoctl_enable_secondary",
289+
"pg_autoctl enable secondary",
290+
"pg_autoctl enable secondary",
291+
[author],
292+
1,
293+
),
294+
(
295+
"ref/pg_autoctl_enable_ssl",
296+
"pg_autoctl enable ssl",
297+
"pg_autoctl enable ssl",
298+
[author],
299+
1,
300+
),
301+
(
302+
"ref/pg_autoctl_enable_monitor",
303+
"pg_autoctl enable monitor",
304+
"pg_autoctl enable monitor",
305+
[author],
306+
1,
307+
),
308+
(
309+
"ref/pg_autoctl_disable_maintenance",
310+
"pg_autoctl disable maintenance",
311+
"pg_autoctl disable maintenance",
312+
[author],
313+
1,
314+
),
315+
(
316+
"ref/pg_autoctl_disable_secondary",
317+
"pg_autoctl disable secondary",
318+
"pg_autoctl disable secondary",
319+
[author],
320+
1,
321+
),
322+
(
323+
"ref/pg_autoctl_disable_ssl",
324+
"pg_autoctl disable ssl",
325+
"pg_autoctl disable ssl",
326+
[author],
327+
1,
328+
),
329+
(
330+
"ref/pg_autoctl_disable_monitor",
331+
"pg_autoctl disable monitor",
332+
"pg_autoctl disable monitor",
333+
[author],
334+
1,
335+
),
336+
(
337+
"ref/pg_autoctl_get_formation_settings",
338+
"pg_autoctl get formation settings",
339+
"pg_autoctl get formation settings",
340+
[author],
341+
1,
342+
),
343+
(
344+
"ref/pg_autoctl_get_formation_number_sync_standbys",
345+
"pg_autoctl get formation number-sync-standbys",
346+
"pg_autoctl get formation number-sync-standbys",
347+
[author],
348+
1,
349+
),
350+
(
351+
"ref/pg_autoctl_get_node_replication_quorum",
352+
"pg_autoctl get node replication-quorum",
353+
"pg_autoctl get node replication-quorum",
354+
[author],
355+
1,
356+
),
357+
(
358+
"ref/pg_autoctl_get_node_candidate_priority",
359+
"pg_autoctl get node candidate-priority",
360+
"pg_autoctl get node candidate-priority",
361+
[author],
362+
1,
363+
),
364+
(
365+
"ref/pg_autoctl_set_formation_number_sync_standbys",
366+
"pg_autoctl set formation number-sync-standbys",
367+
"pg_autoctl set formation number-sync-standbys",
368+
[author],
369+
1,
370+
),
371+
(
372+
"ref/pg_autoctl_set_node_replication_quorum",
373+
"pg_autoctl set node replication-quorum",
374+
"pg_autoctl set node replication-quorum",
375+
[author],
376+
1,
377+
),
378+
(
379+
"ref/pg_autoctl_set_node_candidate_priority",
380+
"pg_autoctl set node candidate-priority",
381+
"pg_autoctl set node candidate-priority",
382+
[author],
383+
1,
384+
),
385+
(
386+
"ref/pg_autoctl_perform_failover",
387+
"pg_autoctl perform failover",
388+
"pg_autoctl perform failover",
389+
[author],
390+
1,
391+
),
392+
(
393+
"ref/pg_autoctl_perform_switchover",
394+
"pg_autoctl perform switchover",
395+
"pg_autoctl perform switchover",
396+
[author],
397+
1,
398+
),
399+
(
400+
"ref/pg_autoctl_perform_promotion",
401+
"pg_autoctl perform promotion",
402+
"pg_autoctl perform promotion",
403+
[author],
404+
1,
405+
),
406+
(
407+
"ref/pg_autoctl_run",
408+
"pg_autoctl run",
409+
"pg_autoctl run",
410+
[author],
411+
1,
412+
),
413+
(
414+
"ref/pg_autoctl_stop",
415+
"pg_autoctl stop",
416+
"pg_autoctl stop",
417+
[author],
418+
1,
419+
),
420+
(
421+
"ref/pg_autoctl_status",
422+
"pg_autoctl status",
423+
"pg_autoctl status",
424+
[author],
425+
1,
426+
),
427+
(
428+
"ref/pg_autoctl_reload",
429+
"pg_autoctl reload",
430+
"pg_autoctl reload",
431+
[author],
432+
1,
433+
),
434+
# ("ref/reference", "pg_autoctl", "pg_auto_failover agent", [author], 1),
175435
(
176436
"ref/configuration",
177437
"pg_autoctl",

‎docs/how-to.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ generally possible to use only some of the many ``pg_autoctl`` commands.
1111
This section of the documentation is a short introduction to the main
1212
commands that are useful when getting started with pg_auto_failover. More
1313
commands are available and help deal with a variety of situations, see the
14-
:ref:`reference` for the whole list.
14+
:ref:`manual` for the whole list.
1515

1616
To understand which replication settings to use in your case, see
1717
:ref:`architecture_basics` section and then the

‎docs/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Welcome to pg_auto_failover's documentation!
77
============================================
88

99
.. toctree::
10-
:maxdepth: 3
10+
:maxdepth: 4
1111
:caption: Contents:
1212

1313
intro
@@ -19,7 +19,7 @@ Welcome to pg_auto_failover's documentation!
1919
fault-tolerance
2020
install
2121
security
22-
ref/reference
22+
ref/manual
2323
ref/configuration
2424
operations
2525
faq

‎docs/operations.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,7 @@ the following commands.
379379

380380
$ pg_autoctl disable monitor --force
381381

382+
382383
3. Create a new monitor node::
383384

384385
$ pg_autoctl create monitor ...
@@ -393,6 +394,9 @@ the following commands.
393394

394395
$ pg_autoctl enable monitor --monitor postgresql://...
395396

397+
See :ref:`pg_autoctl_disable_monitor` and :ref:`pg_autoctl_enable_monitor`
398+
for details about those commands.
399+
396400
This operation relies on the fact that a ``pg_autoctl`` can be operated
397401
without a monitor, and when reconnecting to a new monitor, this process
398402
reset the parts of the node state that comes from the monitor, such as the

‎docs/ref/configuration.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ pg_auto_failover Keeper Service
108108
-------------------------------
109109

110110
For an introduction to the ``pg_autoctl`` commands relevant to the pg_auto_failover
111-
Keeper configuration, please see :ref:`pg_autoctl_configuration`.
111+
Keeper configuration, please see :ref:`pg_autoctl_config`.
112112

113113
An example configuration file looks like the following::
114114

‎docs/ref/manual.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.. _manual:
2+
3+
Manual Pages
4+
============
5+
6+
The ``pg_autoctl`` tool hosts many commands and sub-commands. Each of them
7+
have their own manual page.
8+
9+
.. toctree::
10+
:maxdepth: 1
11+
:caption: Manual Pages:
12+
13+
pg_autoctl
14+
pg_autoctl_create
15+
pg_autoctl_drop
16+
pg_autoctl_config
17+
pg_autoctl_show
18+
pg_autoctl_enable
19+
pg_autoctl_disable
20+
pg_autoctl_get
21+
pg_autoctl_set
22+
pg_autoctl_perform
23+
pg_autoctl_do
24+
pg_autoctl_run
25+
pg_autoctl_stop
26+
pg_autoctl_reload
27+
pg_autoctl_status

0 commit comments

Comments
 (0)