[pbs-devel] [PATCH proxmox-backup] docs: add labels for onlinehelp anchors

[pbs-devel] [PATCH proxmox-backup] docs: add labels for onlinehelp anchors

[Oguz Bektas]

define references for some sections for easy adding into onlinehelpinfo
---
 docs/administration-guide.rst | 34 +++++++++++++++++++++++++++++++++-
 docs/installation.rst         |  3 +++
 docs/introduction.rst         |  4 ++++
 docs/package-repositories.rst |  2 ++
 4 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
index e6357a3e..e514beb1 100644
--- a/docs/administration-guide.rst
+++ b/docs/administration-guide.rst
@@ -7,6 +7,8 @@ Backup Management
 Terminology
 -----------
 
+.. _chapter-backup-explanation:
+
 Backup Content
 ~~~~~~~~~~~~~~
 
@@ -121,6 +123,9 @@ uniquely identifies a specific backup within a datastore.
 As you can see, the time format is RFC3399_ with Coordinated
 Universal Time (UTC_, identified by the trailing *Z*).
 
+
+.. _chapter-backup-manager:
+
 Backup Server Management
 ------------------------
 
@@ -215,6 +220,9 @@ display S.M.A.R.T. attributes using the command:
 
   # proxmox-backup-manager disk smart-attributes sdX
 
+
+.. _chapter-datastore-config:
+
 Datastore Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -324,6 +332,7 @@ directories will store the chunked data after a backup operation has been execut
  276490 drwxr-x--- 1 backup backup 1.1M Jul  8 12:35 .
 
 
+.. _chapter-user-management:
 
 User Management
 ~~~~~~~~~~~~~~~
@@ -400,6 +409,8 @@ Or completely remove the user with:
   # proxmox-backup-manager user remove john@pbs
 
 
+.. _chapter-access-control:
+
 Access Control
 ~~~~~~~~~~~~~~
 
@@ -472,6 +483,9 @@ A single user can be assigned multiple permission sets for different data stores
   remote (see `Remote` below) and ``{storename}`` is the name of the data store on
   the remote.
 
+
+.. _chapter-network-management:
+
 Network Management
 ~~~~~~~~~~~~~~~~~~
 Proxmox Backup Server provides an interface for network configuration, through the
@@ -538,6 +552,8 @@ configuration file, the command is:
 You can also configure DNS settings using the ``dns`` subcommand of
 ``proxmox-backup-manager``.
 
+.. _chapter-backup-remote:
+
 :term:`Remote`
 ~~~~~~~~~~~~~~
 
@@ -575,6 +591,9 @@ Use the ``list``, ``show``, ``update``, ``remove`` subcommands of
   # proxmox-backup-manager remote remove pbs2
 
 
+.. _chapter-sync-jobs:
+
+
 Sync Jobs
 ~~~~~~~~~
 
@@ -595,6 +614,9 @@ provide it with a :term:`schedule` to run regularly. The
   └────────────┴───────┴────────┴──────────────┴───────────┴─────────┘
   # proxmox-backup-manager sync-job remove pbs2-local
 
+
+.. _chapter-gc:
+
 Garbage Collection
 ~~~~~~~~~~~~~~~~~~
 You can monitor and run :ref:`garbage collection <garbage-collection>` on the
@@ -603,6 +625,7 @@ Proxmox Backup Server using the ``garbage-collection`` subcommand of
 collection on an entire data store and the ``status`` subcommand to see
 attributes relating to the :ref:`garbage collection <garbage-collection>`.
 
+.. _chapter-backup-client:
 
 Backup Client usage
 -------------------
@@ -674,7 +697,7 @@ Please use the following environment variables to modify output behavior:
    format if you need to process the output.
 
 
-.. _creating-backups:
+.. _chapter-creating-backups:
 
 Creating Backups
 ~~~~~~~~~~~~~~~~
@@ -832,6 +855,8 @@ Restoring this backup will result in:
     restored/subfolder1:
     .  ..  file2
 
+.. _chapter-encryption:
+
 Encryption
 ~~~~~~~~~~
 
@@ -876,6 +901,7 @@ You can also use ``proxmox-backup-client key`` to create an RSA public/private
 key pair, which can be used to store an encrypted version of the symmetric
 backup encryption key alongside each backup and recover it later.
 
+
 To set up a master key:
 
 1. Create an encryption key for the backup:
@@ -952,6 +978,9 @@ To set up a master key:
   you should consider keeping a paper copy of this key locked away in
   a safe place.
 
+
+.. _chapter-restore:
+
 Restoring Data
 ~~~~~~~~~~~~~~
 
@@ -1093,6 +1122,9 @@ To unmount the filesystem use the ``umount`` command on the mountpoint:
 
   # umount /mnt/mountpoint
 
+
+.. _chapter-login-logout:
+
 Login and Logout
 ~~~~~~~~~~~~~~~~
 
diff --git a/docs/installation.rst b/docs/installation.rst
index 7d4055b6..29f45fe3 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,3 +1,6 @@
+
+.. _chapter-installation:
+
 Installation
 ============
 
diff --git a/docs/introduction.rst b/docs/introduction.rst
index 0b0e3ae3..28b634a3 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -76,6 +76,8 @@ Main Features
    phase is over.
 
 
+.. _data-backup-reasons:
+
 Reasons for Data Backup?
 ------------------------
 
@@ -127,6 +129,8 @@ language.
 
 .. todo:: further explain the software stack
 
+.. _get-help:
+
 Getting Help
 ------------
 
diff --git a/docs/package-repositories.rst b/docs/package-repositories.rst
index c3883b8b..6364f603 100644
--- a/docs/package-repositories.rst
+++ b/docs/package-repositories.rst
@@ -128,6 +128,8 @@ Here, the output should be:
       deb http://security.debian.org/debian-security buster/updates main contrib
 
 
+.. _chapter-beta-repo:
+
 `Proxmox Backup`_ Beta Repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.20.1

Re: [pbs-devel] [PATCH proxmox-backup] docs: add labels for onlinehelp anchors

[Thomas Lamprecht]

On 03.09.20 14:41, Oguz Bektas wrote:
> define references for some sections for easy adding into onlinehelpinfo

Thanks! ideally you'd already add, at least some, uses in the UI as "onlineHelp:" 
references, so that more help buttons are shown or work there.

> ---
>  docs/administration-guide.rst | 34 +++++++++++++++++++++++++++++++++-
>  docs/installation.rst         |  3 +++
>  docs/introduction.rst         |  4 ++++
>  docs/package-repositories.rst |  2 ++
>  4 files changed, 42 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
> index e6357a3e..e514beb1 100644
> --- a/docs/administration-guide.rst
> +++ b/docs/administration-guide.rst
> @@ -7,6 +7,8 @@ Backup Management
>  Terminology
>  -----------
>  
> +.. _chapter-backup-explanation:

I'd drop the "chapter-" prefix, rather use the top-level (abbreviated, if long)
as prefix for lower level heading references.

E.g., in PVE we use "qm" for all things in qemu-server, "qm_hard_disk", or an additional
level: "qm_hard_disk_bus", and so on.

This could be

.. _term-backup-content

for example. But using the same prefix for all references is worse than using none
at all, IMO.

Re: [pbs-devel] [PATCH proxmox-backup] docs: add labels for onlinehelp anchors

[Oguz Bektas]

hi,


On Fri, Sep 04, 2020 at 02:27:48PM +0200, Thomas Lamprecht wrote:
> On 03.09.20 14:41, Oguz Bektas wrote:
> > define references for some sections for easy adding into onlinehelpinfo
> 
> Thanks! ideally you'd already add, at least some, uses in the UI as "onlineHelp:" 
> references, so that more help buttons are shown or work there.

thanks
will do that as well - i wasn't sure which parts really needed to have
the button so i didn't add any. it'll be in the v2

> 
> > ---
> >  docs/administration-guide.rst | 34 +++++++++++++++++++++++++++++++++-
> >  docs/installation.rst         |  3 +++
> >  docs/introduction.rst         |  4 ++++
> >  docs/package-repositories.rst |  2 ++
> >  4 files changed, 42 insertions(+), 1 deletion(-)
> > 
> > diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
> > index e6357a3e..e514beb1 100644
> > --- a/docs/administration-guide.rst
> > +++ b/docs/administration-guide.rst
> > @@ -7,6 +7,8 @@ Backup Management
> >  Terminology
> >  -----------
> >  
> > +.. _chapter-backup-explanation:
> 
> I'd drop the "chapter-" prefix, rather use the top-level (abbreviated, if long)
> as prefix for lower level heading references.


alright, i'll switch up the toplevel ones to that and remove it from the
others.

> 
> E.g., in PVE we use "qm" for all things in qemu-server, "qm_hard_disk", or an additional
> level: "qm_hard_disk_bus", and so on.
> 
> This could be
> 
> .. _term-backup-content
> 
> for example. But using the same prefix for all references is worse than using none
> at all, IMO.
> 

yeah, i'll try to come up with better names :)