[PATCH 0/4] docs: Fix generation of hyperlinks and improve backup/checkpoint docs
Peter Krempa (4): docs: newapi: Consider also 'https://' links in the API generator XSL virDomainCheckpointCreateXML: Don't use HTML in function docs and fix link virDomainCheckpointCreateXML: Add disclaimer about creating checkpoints virDomainBackupGetXMLDesc: Fix and use full link to XML documentation docs/newapi.xsl | 5 +++++ src/libvirt-domain-checkpoint.c | 12 +++++++++++- src/libvirt-domain.c | 2 +- 3 files changed, 17 insertions(+), 2 deletions(-) -- 2.37.1
We converted exclusively to https links so the generator should wrap those in appropriate link tags too. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/newapi.xsl | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index e56a5f2a27..f2e8bd5334 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -131,6 +131,11 @@ <xsl:value-of select="$token"/> </a> </xsl:when> + <xsl:when test="starts-with($token, 'https://')"> + <a href="{$token}"> + <xsl:value-of select="$token"/> + </a> + </xsl:when> <xsl:when test="starts-with($token, '<http://') and contains($token, '>')"> <xsl:variable name="link" select="substring(substring-before($token, '>'), 2)"/> -- 2.37.1
Fix the link target after the conversion of the XML description to RST which renamed anchors and drop the <a> tag from the C code comment. Apart from not working properly in the .c file it didn't work in the generated docs either as the brackets were escaped. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain-checkpoint.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index f58f1b4f8f..de747aff01 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -114,7 +114,7 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * kicking off a backup job with virDomainBackupBegin(); however, it * is also possible to start a checkpoint without a backup. * - * See <a href="formatcheckpoint.html#CheckpointAttributes">Checkpoint XML</a> + * See https://www.libvirt.org/formatcheckpoint.html#checkpoint-xml * for more details on @xmlDesc. In particular, some hypervisors may require * particular disk formats, such as qcow2, in order to support this * command; where @xmlDesc can be used to limit the checkpoint to a working -- 2.37.1
Checkpoints created via virDomainCheckpointCreateXML are generally not very useful as they need to be coupled with a backup. Add a disclaimer to the docs explaining why users should use virDomainBackupBegin instead. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain-checkpoint.c | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index de747aff01..078e999bf3 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -142,6 +142,16 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * present, an error is thrown. This flag is incompatible with * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE. * + * Note: A checkpoint represent s point in time since which blocks changed by + * the hypervisor are tracked. The tracking of changed blocks notes only whether + * a block was modified, but does not preserve the old contents. This means that + * for a checkpoint to be generally usable for doing an incremental backup it's + * required to perform a backup at the same time as taking the checkpoint. + * This is done via the virDomainBackupBegin API, which also allows to create + * a checkpoint at the same time. virDomainCheckpointCreateXML is generally not + * useful for creating checkpoints but rather only for re-creating the libvirt + * metadata. + * * Returns an (opaque) new virDomainCheckpointPtr on success or NULL * on failure. * -- 2.37.1
On 8/23/22 6:32 AM, Peter Krempa wrote:
Checkpoints created via virDomainCheckpointCreateXML are generally not very useful as they need to be coupled with a backup.
Add a disclaimer to the docs explaining why users should use virDomainBackupBegin instead.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain-checkpoint.c | 10 ++++++++++ 1 file changed, 10 insertions(+)
diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index de747aff01..078e999bf3 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -142,6 +142,16 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * present, an error is thrown. This flag is incompatible with * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE. * + * Note: A checkpoint represent s point in time since which blocks changed by + * the hypervisor are tracked.
extra space in "represent s" Also, I think it would be more clearly understood if we changed "since" to "after". "Note: a checkpoint represents a point in time after which blocks changed..."
This means that + * for a checkpoint to be generally usable for doing an incremental backup it's + * required to perform a backup at the same time as taking the checkpoint.
I might suggest something like: "The main purpose of checkpoints is to enable incremental backups. But for a checkpoint to be useful for this purpose, a backup should be performed at the same time as the checkpoint is created."
+ * This is done via the virDomainBackupBegin API, which also allows to create + * a checkpoint at the same time. virDomainCheckpointCreateXML is generally not + * useful for creating checkpoints but rather only for re-creating the libvirt + * metadata.
my suggestion here: "This is done via the virDomainBackupBegin API, which also allows to create a checkpoint at the same time. Creating checkpoints with virDomainCheckpointCreateXML is generally only useful for re-creating the libvirt metadata" Reviewed-by: Jonathon Jongsma <jjongsma@redhat.com>
Use the full link to the backup XML description page and use the proper anchor after html->RST coversion. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 842663a608..80a6f0f269 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -13582,7 +13582,7 @@ virDomainAgentSetResponseTimeout(virDomainPtr domain, * * virDomainBackupGetXMLDesc() can be called to learn actual * values selected. For more information, see - * formatcheckpoint.html#BackupAttributes. + * https://www.libvirt.org/formatbackup.html#backup-xml * * The @checkpointXML parameter is optional; if non-NULL, then libvirt * behaves as if virDomainCheckpointCreateXML() were called to create -- 2.37.1
On 8/23/22 6:32 AM, Peter Krempa wrote:
Peter Krempa (4): docs: newapi: Consider also 'https://' links in the API generator XSL virDomainCheckpointCreateXML: Don't use HTML in function docs and fix link virDomainCheckpointCreateXML: Add disclaimer about creating checkpoints virDomainBackupGetXMLDesc: Fix and use full link to XML documentation
docs/newapi.xsl | 5 +++++ src/libvirt-domain-checkpoint.c | 12 +++++++++++- src/libvirt-domain.c | 2 +- 3 files changed, 17 insertions(+), 2 deletions(-)
With comments on patch 3 Reviewed-by: Jonathon Jongsma <jjongsma@redhat.com>
participants (2)
-
Jonathon Jongsma -
Peter Krempa