5
0
mirror of git://git.proxmox.com/git/proxmox-backup.git synced 2025-01-20 14:03:53 +03:00

docs: let sphinx build man pages for better integration and less cruft

rst2man is only good for use in projects that don't use sphinx
already, as there it can help to avoid bringing in the full sphinx
dependencies and be easier to manage (as long as it stay small).

But we already use sphinx, so there's no point in managing the manual
pages in a separate, semi-related way that is quite restricted as we
have no access to sphinx infrastructure like conf.py defined
variables and helpers for things like the current version.

Besides that, we're rather big, so the complexity of sphinx can
shine, e.g., see the diffstat report from switching out rst2man for
sphinx:

22 files changed, 74 insertions(+), 347 deletions(-)

so 273 lines less in total is rather nice.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
This commit is contained in:
Thomas Lamprecht 2022-07-14 16:41:43 +02:00
parent 5b5f18eb38
commit ed873dc6a4
22 changed files with 74 additions and 347 deletions

View File

@ -95,117 +95,65 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
all: ${MAN1_PAGES} ${MAN5_PAGES}
# Build manual pages using rst2man
pxar/synopsis.rst: ${COMPILEDIR}/pxar
${COMPILEDIR}/pxar printdoc > pxar/synopsis.rst
pxar.1: pxar/man1.rst pxar/description.rst pxar/synopsis.rst
rst2man $< >$@
pmtx/synopsis.rst: ${COMPILEDIR}/pmtx
${COMPILEDIR}/pmtx printdoc > pmtx/synopsis.rst
pmtx.1: pmtx/man1.rst pmtx/description.rst pmtx/synopsis.rst
rst2man $< >$@
pmt/synopsis.rst: ${COMPILEDIR}/pmt
${COMPILEDIR}/pmt printdoc > pmt/synopsis.rst
pmt.1: pmt/man1.rst pmt/description.rst pmt/options.rst pmt/synopsis.rst
rst2man $< >$@
config/datastore/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen datastore.cfg >$@
datastore.cfg.5: config/datastore/man5.rst config/datastore/config.rst config/datastore/format.rst
rst2man $< >$@
config/user/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen user.cfg >$@
user.cfg.5: config/user/man5.rst config/user/config.rst config/user/format.rst
rst2man $< >$@
config/remote/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen remote.cfg >$@
remote.cfg.5: config/remote/man5.rst config/remote/config.rst config/remote/format.rst
rst2man $< >$@
config/sync/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen sync.cfg >$@
sync.cfg.5: config/sync/man5.rst config/sync/config.rst config/sync/format.rst
rst2man $< >$@
config/verification/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen verification.cfg >$@
verification.cfg.5: config/verification/man5.rst config/verification/config.rst config/verification/format.rst
rst2man $< >$@
config/acl/roles.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen "config::acl::Role" >$@
acl.cfg.5: config/acl/man5.rst config/acl/roles.rst config/acl/format.rst
rst2man $< >$@
config/media-pool/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen media-pool.cfg >$@
media-pool.cfg.5: config/media-pool/man5.rst config/media-pool/config.rst config/media-pool/format.rst
rst2man $< >$@
config/tape/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen tape.cfg >$@
tape.cfg.5: config/tape/man5.rst config/tape/config.rst config/tape/format.rst
rst2man $< >$@
config/tape-job/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen tape-job.cfg >$@
tape-job.cfg.5: config/tape-job/man5.rst config/tape-job/config.rst config/tape-job/format.rst
rst2man $< >$@
proxmox-tape/synopsis.rst: ${COMPILEDIR}/proxmox-tape
${COMPILEDIR}/proxmox-tape printdoc > proxmox-tape/synopsis.rst
proxmox-tape.1: proxmox-tape/man1.rst proxmox-tape/description.rst proxmox-tape/synopsis.rst
rst2man $< >$@
proxmox-backup-client/synopsis.rst: ${COMPILEDIR}/proxmox-backup-client
${COMPILEDIR}/proxmox-backup-client printdoc > proxmox-backup-client/synopsis.rst
proxmox-backup-client/catalog-shell-synopsis.rst: ${COMPILEDIR}/dump-catalog-shell-cli
${COMPILEDIR}/dump-catalog-shell-cli > proxmox-backup-client/catalog-shell-synopsis.rst
proxmox-backup-client.1: proxmox-backup-client/man1.rst proxmox-backup-client/description.rst proxmox-backup-client/synopsis.rst proxmox-backup-client/catalog-shell-synopsis.rst
rst2man $< >$@
proxmox-backup-manager/synopsis.rst: ${COMPILEDIR}/proxmox-backup-manager
${COMPILEDIR}/proxmox-backup-manager printdoc > proxmox-backup-manager/synopsis.rst
proxmox-backup-manager.1: proxmox-backup-manager/man1.rst proxmox-backup-manager/description.rst proxmox-backup-manager/synopsis.rst
rst2man $< >$@
proxmox-backup-proxy.1: proxmox-backup-proxy/man1.rst proxmox-backup-proxy/description.rst
rst2man $< >$@
proxmox-file-restore/synopsis.rst: ${COMPILEDIR}/proxmox-file-restore
${COMPILEDIR}/proxmox-file-restore printdoc > proxmox-file-restore/synopsis.rst
proxmox-file-restore.1: proxmox-file-restore/man1.rst proxmox-file-restore/description.rst proxmox-file-restore/synopsis.rst
rst2man $< >$@
proxmox-backup-debug/synopsis.rst: ${COMPILEDIR}/proxmox-backup-debug
${COMPILEDIR}/proxmox-backup-debug printdoc > proxmox-backup-debug/synopsis.rst
proxmox-backup-debug.1: proxmox-backup-debug/man1.rst proxmox-backup-debug/description.rst proxmox-backup-debug/synopsis.rst
rst2man $< >$@
${MAN1_PAGES} ${MAN5_PAGES}: man-pages
.PHONY: man-pages
man-pages: ${GENERATED_SYNOPSIS}
${SPHINXBUILD} ${SPHINXOPTS} -b man ./ ${BUILDDIR}/man
.PHONY: onlinehelpinfo
onlinehelpinfo:
@ -259,12 +207,11 @@ clean:
rm -r -f *~ *.1 ${BUILDDIR} ${GENERATED_SYNOPSIS} api-viewer/apidata.js
rm -f api-viewer/apidoc.js lto-barcode/lto-barcode-generator.js prune-simulator/prune-simulator.js
install_manual_pages: ${MAN1_PAGES} ${MAN5_PAGES}
install_manual_pages: man-pages
install -dm755 $(DESTDIR)$(MAN1DIR)
for i in ${MAN1_PAGES}; do install -m755 $$i $(DESTDIR)$(MAN1DIR)/ ; done
for i in ${MAN1_PAGES}; do install -m755 ${BUILDDIR}/man/$$i $(DESTDIR)$(MAN1DIR)/ ; done
install -dm755 $(DESTDIR)$(MAN5DIR)
for i in ${MAN5_PAGES}; do install -m755 $$i $(DESTDIR)$(MAN5DIR)/ ; done
for i in ${MAN5_PAGES}; do install -m755 ${BUILDDIR}/man/$$i $(DESTDIR)$(MAN5DIR)/ ; done
install_html: html
install -dm755 $(DESTDIR)$(DOCDIR)

View File

@ -88,6 +88,31 @@ version = vstr(os.getenv('DEB_VERSION_UPSTREAM'))
# The full version, including alpha/beta/rc tags.
release = vstr(os.getenv('DEB_VERSION'))
man_pages = [
# CLI
('proxmox-backup-client/man1', 'proxmox-backup-client', 'Command line tool for Backup and Restore', [author], 1),
('proxmox-backup-manager/man1', 'proxmox-backup-manager', 'Command line tool to manage and configure the backup server.', [author], 1),
('proxmox-backup-debug/man1', 'proxmox-backup-debug', 'Debugging command line tool for Backup and Restore', [author], 1),
('proxmox-backup-proxy/man1', 'proxmox-backup-proxy', 'Proxmox Backup Public API Server', [author], 1),
('proxmox-backup/man1', 'proxmox-backup', 'Proxmox Backup Local API Server', [author], 1),
('proxmox-file-restore/man1', 'proxmox-file-restore', 'CLI tool for restoring files and directories from Proxmox Backup Server archives', [author], 1),
('proxmox-tape/man1', 'proxmox-tape', 'Proxmox Tape Backup CLI Tool', [author], 1),
('pxar/man1', 'pxar', 'Proxmox File Archive CLI Tool', [author], 1),
('pmt/man1', 'pmt', 'Control Linux Tape Devices', [author], 1),
('pmtx/man1', 'pmtx', 'Control SCSI media changer devices (tape autoloaders)', [author], 1),
# configs
('config/acl/man5', 'acl.cfg', 'Access Control Configuration', [author], 5),
('config/datastore/man5', 'datastore.cfg', 'Datastore Configuration', [author], 5),
('config/media-pool/man5', 'media-pool.cfg', 'Media Pool Configuration', [author], 5),
('config/remote/man5', 'remote.cfg', 'Remote Server Configuration', [author], 5),
('config/sync/man5', 'sync.cfg', 'Synchronization Job Configuration', [author], 5),
('config/tape-job/man5', 'tape-job.cfg', 'Tape Job Configuration', [author], 5),
('config/tape/man5', 'tape.cfg', 'Tape Drive and Changer Configuration', [author], 5),
('config/user/man5', 'user.cfg', 'User Configuration', [author], 5),
('config/verification/man5', 'verification.cfg', 'Verification Job Configuration', [author], 5),
]
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
@ -102,14 +127,14 @@ language = None
# Else, today_fmt is used as the format for a strftime call.
today_fmt = '%A, %d %B %Y'
suppress_warnings = [ 'toc.excluded' ]
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = [
'_build', 'Thumbs.db', '.DS_Store',
'*/man1.rst',
'certificate-management.rst',
'config/*/man5.rst',
'epilog.rst',
'pbs-copyright.rst',
'local-zfs.rst',

View File

@ -1,21 +1,11 @@
==========================
=======
acl.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
Access Control Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
=======
Description
===========
The file /etc/proxmox-backup/user.cfg is a configuration file for Proxmox
The file /etc/proxmox-backup/acl.cfg is a configuration file for Proxmox
Backup Server. It contains the access control configuration for the API.
File Format
@ -23,7 +13,6 @@ File Format
.. include:: format.rst
Roles
=====
@ -31,5 +20,4 @@ The following roles exist:
.. include:: roles.rst
.. include:: ../../pbs-copyright.rst

View File

@ -1,16 +1,6 @@
==========================
=============
datastore.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
Datastore Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
=============
Description
===========
@ -23,11 +13,9 @@ File Format
.. include:: format.rst
Options
=======
.. include:: config.rst
.. include:: ../../pbs-copyright.rst

View File

@ -2,16 +2,6 @@
media-pool.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
Media Pool Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
Description
===========
@ -19,17 +9,14 @@ The file /etc/proxmox-backup/media-pool.cfg is a configuration file
for Proxmox Backup Server. It contains the medila pool configuration
for tape backups.
File Format
===========
.. include:: format.rst
Options
=======
.. include:: config.rst
.. include:: ../../pbs-copyright.rst

View File

@ -1,16 +1,6 @@
==========================
==========
remote.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
Remote Server Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
==========
Description
===========
@ -19,17 +9,14 @@ The file /etc/proxmox-backup/remote.cfg is a configuration file for
Proxmox Backup Server. It contains information about remote servers,
usable for synchronization jobs.
File Format
===========
.. include:: format.rst
Options
=======
.. include:: config.rst
.. include:: ../../pbs-copyright.rst

View File

@ -1,35 +1,21 @@
==========================
========
sync.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
Synchronization Job Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
========
Description
===========
The file /etc/proxmox-backup/sync.cfg is a configuration file for
Proxmox Backup Server. It contains the synchronization job
configuration.
The file /etc/proxmox-backup/sync.cfg is a configuration file for Proxmox
Backup Server. It contains the synchronization job configuration.
File Format
===========
.. include:: format.rst
Options
=======
.. include:: config.rst
.. include:: ../../pbs-copyright.rst

View File

@ -1,16 +1,6 @@
==========================
============
tape-job.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
Tape Job Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
============
Description
===========
@ -18,13 +8,11 @@ Description
The file ``/etc/proxmox-backup/tape-job.cfg`` is a configuration file for
Proxmox Backup Server. It contains the tape job configuration.
File Format
===========
.. include:: format.rst
Options
=======

View File

@ -1,16 +1,6 @@
==========================
========
tape.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
Tape Drive and Changer Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
========
Description
===========
@ -23,11 +13,9 @@ File Format
.. include:: format.rst
Options
=======
.. include:: config.rst
.. include:: ../../pbs-copyright.rst

View File

@ -1,16 +1,6 @@
==========================
========
user.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
User Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
========
Description
===========
@ -23,11 +13,9 @@ File Format
.. include:: format.rst
Options
=======
.. include:: config.rst
.. include:: ../../pbs-copyright.rst

View File

@ -1,35 +1,21 @@
==========================
================
verification.cfg
==========================
.. include:: ../../epilog.rst
-------------------------------------------------------------
Verification Job Configuration
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 5
================
Description
===========
The file /etc/proxmox-backup/sync.cfg is a configuration file for
Proxmox Backup Server. It contains the verification job
configuration.
The file /etc/proxmox-backup/sync.cfg is a configuration file for Proxmox
Backup Server. It contains the verification job configuration.
File Format
===========
.. include:: format.rst
Options
=======
.. include:: config.rst
.. include:: ../../pbs-copyright.rst

View File

@ -1,36 +1,22 @@
==========================
===
pmt
==========================
.. include:: ../epilog.rst
-------------------------------------------------------------
Control Linux Tape Devices
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
===
Synopsis
========
.. include:: synopsis.rst
Common Options
==============
.. include:: options.rst
Description
===========
.. include:: description.rst
ENVIRONMENT
===========
@ -38,5 +24,4 @@ ENVIRONMENT
:PROXMOX_TAPE_DRIVE: If set, replaces the `--drive` option.
.. include:: ../pbs-copyright.rst

View File

@ -2,23 +2,11 @@
pmtx
==========================
.. include:: ../epilog.rst
-------------------------------------------------------------
Control SCSI media changer devices (tape autoloaders)
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
Synopsis
==========
.. include:: synopsis.rst
Common Options
==============
@ -38,13 +26,11 @@ parameter. It accepts the following values:
:``json-pretty``: JSON (multiple lines, nicely formatted).
Description
============
.. include:: description.rst
ENVIRONMENT
===========
@ -53,5 +39,4 @@ ENVIRONMENT
:PROXMOX_TAPE_DRIVE: If set, use the Proxmox Backup Server
configuration to find the associated changer device.
.. include:: ../pbs-copyright.rst

View File

@ -1,17 +1,6 @@
==========================
=====================
proxmox-backup-client
==========================
.. include:: ../epilog.rst
-------------------------------------------------------------
Command line tool for Backup and Restore
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
=====================
Synopsis
==========

View File

@ -1,20 +1,9 @@
==========================
====================
proxmox-backup-debug
==========================
.. include:: ../epilog.rst
-------------------------------------------------------------
Debugging command line tool for Backup and Restore
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
====================
Synopsis
==========
========
.. include:: synopsis.rst
@ -23,11 +12,9 @@ Common Options
.. include:: ../output-format.rst
Description
============
.. include:: description.rst
.. include:: ../pbs-copyright.rst

View File

@ -2,17 +2,6 @@
proxmox-backup-manager
==========================
.. include:: ../epilog.rst
-------------------------------------------------------------
Command line tool to manage and configure the backup server.
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
Synopsis
========
@ -25,4 +14,3 @@ Description
.. include:: ../pbs-copyright.rst

View File

@ -1,5 +1,4 @@
This daemon exposes the whole Proxmox Backup Server API on TCP port
8007 using HTTPS. It runs as user ``backup`` and has very limited
permissions. Operations requiring more permissions are forwarded to
the local ``proxmox-backup`` service.
This daemon exposes the whole Proxmox Backup Server API on TCP port 8007 using
HTTPS. It runs as user ``backup`` and has very limited permissions. Operations
requiring more permissions are forwarded to the local ``proxmox-backup``
service.

View File

@ -2,17 +2,6 @@
proxmox-backup-proxy
==========================
.. include:: ../epilog.rst
-------------------------------------------------------------
Proxmox Backup Public API Server
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
Synopsis
==========
@ -36,6 +25,4 @@ Description
.. include:: description.rst
.. include:: ../pbs-copyright.rst

View File

@ -2,17 +2,6 @@
proxmox-backup
==========================
.. include:: ../epilog.rst
-------------------------------------------------------------
Proxmox Backup Local API Server
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
Synopsis
==========
@ -31,11 +20,9 @@ For debugging, you can start the daemon in foreground using::
.. NOTE:: You need to stop the service before starting the daemon in
foreground.
Description
============
.. include:: description.rst
.. include:: ../pbs-copyright.rst

View File

@ -1,28 +1,15 @@
==========================
====================
proxmox-file-restore
==========================
.. include:: ../epilog.rst
-----------------------------------------------------------------------
Command line tool for restoring files and directories from PBS archives
-----------------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
====================
Synopsis
==========
========
.. include:: synopsis.rst
Description
============
.. include:: description.rst
.. include:: ../pbs-copyright.rst

View File

@ -1,17 +1,6 @@
==========================
============
proxmox-tape
==========================
.. include:: ../epilog.rst
-------------------------------------------------------------
Proxmox Tape Backup Command Line Tool
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
============
Synopsis
========
@ -23,6 +12,4 @@ Description
.. include:: description.rst
.. include:: ../pbs-copyright.rst

View File

@ -1,21 +1,10 @@
==========================
====
pxar
==========================
.. include:: ../epilog.rst
====
.. Avoid errors with sphinx ref role
.. role:: ref(emphasis)
-------------------------------------------------------------
Proxmox File Archive Command Line Tool
-------------------------------------------------------------
:Author: |AUTHOR|
:Version: Version |VERSION|
:Manual section: 1
Synopsis
==========
@ -26,5 +15,4 @@ Description
.. include:: description.rst
.. include:: ../pbs-copyright.rst