doc: improve generated scion and scion-pki documentation

doc/BUILD.bazel

@@ -1 +1,9 @@
+load("@rules_python//python:pip.bzl", "compile_pip_requirements")
+
+compile_pip_requirements(
+    name = "requirements",
+    requirements_in = ":requirements.in",
+    requirements_txt = ":requirements.txt",
+)
+
 exports_files(["PathPolicy.md"])

doc/command/scion-pki/scion-pki.md

@@ -0,0 +1,32 @@
+---
+orphan: true
+---
+
+(app-scion-pki)=
+
+# scion-pki
+
+SCION Control Plane PKI Management Tool
+## Options
+
+```
+  -h, --help   help for scion-pki
+```
+## SEE ALSO
+
+* [scion-pki certificate](scion-pki_certificate.md)	 - Manage certificates for the SCION control plane PKI.
+* [scion-pki completion](scion-pki_completion.md)	 - Generate the autocompletion script for the specified shell
+* [scion-pki key](scion-pki_key.md)	 - Manage private and public keys
+* [scion-pki trc](scion-pki_trc.md)	 - Manage TRCs for the SCION control plane PKI
+* [scion-pki version](scion-pki_version.md)	 - Show the scion-pki version information
+
+```{toctree}
+---
+hidden: true
+---
+scion-pki_certificate
+scion-pki_completion
+scion-pki_key
+scion-pki_trc
+scion-pki_version
+```

doc/command/scion-pki/scion-pki_certificate.md

@@ -0,0 +1,39 @@
+---
+orphan: true
+---
+
+(app-scion-pki-certificate)=
+
+# scion-pki certificate
+
+Manage certificates for the SCION control plane PKI.
+## Options
+
+```
+  -h, --help   help for certificate
+```
+## SEE ALSO
+
+* [scion-pki](scion-pki.md)	 - SCION Control Plane PKI Management Tool
+* [scion-pki certificate create](scion-pki_certificate_create.md)	 - Create a certificate or certificate signing request
+* [scion-pki certificate fingerprint](scion-pki_certificate_fingerprint.md)	 - Calculate the SHA256 fingerprint of a certificate or certificate chain
+* [scion-pki certificate inspect](scion-pki_certificate_inspect.md)	 - Inspect a certificate or a certificate signing request
+* [scion-pki certificate match](scion-pki_certificate_match.md)	 - Match the certificate with other trust objects
+* [scion-pki certificate renew](scion-pki_certificate_renew.md)	 - Renew an AS certificate
+* [scion-pki certificate sign](scion-pki_certificate_sign.md)	 - Sign a certificate based on a certificate signing request
+* [scion-pki certificate validate](scion-pki_certificate_validate.md)	 - Validate a SCION cert according to its type
+* [scion-pki certificate verify](scion-pki_certificate_verify.md)	 - Verify a certificate chain
+
+```{toctree}
+---
+hidden: true
+---
+scion-pki_certificate_create
+scion-pki_certificate_fingerprint
+scion-pki_certificate_inspect
+scion-pki_certificate_match
+scion-pki_certificate_renew
+scion-pki_certificate_sign
+scion-pki_certificate_validate
+scion-pki_certificate_verify
+```

doc/command/scion-pki/scion-pki_certificate_create.rst → doc/command/scion-pki/scion-pki_certificate_create.md

@@ -1,38 +1,36 @@
-:orphan:
+---
+orphan: true
+---
 
-.. _scion-pki_certificate_create:
+(app-scion-pki-certificate-create)=
 
-scion-pki certificate create
-----------------------------
+# scion-pki certificate create
 
 Create a certificate or certificate signing request
-
-Synopsis
-~~~~~~~~
-
+## Synopsis
 
 'create' generates a certificate or a certificate signing request (CSR).
 
 The command takes the following positional arguments:
 
-- <subject-template> is the template for the certificate subject distinguished name.
-- <crt-file> is the file path where the certificate or certificate requests is
+- **subject-template** is the template for the certificate subject distinguished name.
+- **crt-file** is the file path where the certificate or certificate requests is
   written to. The parent directory must exist and must be writable.
-- <key-file> is the file path where the fresh private key is written to. The
+- **key-file** is the file path where the fresh private key is written to. The
   parent directory must exist and must be writable.
 
 By default, the command creates a SCION control-plane PKI AS certificate. Another
-certificate type can be selected by providing the \--profile flag. If a certificate
-chain is desired, specify the \--bundle flag.
+certificate type can be selected by providing the --profile flag. If a certificate
+chain is desired, specify the --bundle flag.
 
-A fresh key is created in the provided <key-file>, unless the \--key flag is set.
-If the \--key flag is set, an existing private key is used and the <key-file> is
+A fresh key is created in the provided key-file, unless the --key flag is set.
+If the --key flag is set, an existing private key is used and the key-file is
 ignored.
 
-The \--ca and \--ca-key flags are required if a AS certificate or CA certificate
+The --ca and --ca-key flags are required if a AS certificate or CA certificate
 is being created. Otherwise, they are not allowed.
 
-The \--not-before and \--not-after flags can either be a timestamp or a relative
+The --not-before and --not-after flags can either be a timestamp or a relative
 time offset from the current time.
 
 A timestamp can be provided in two different formats: unix timestamp and
@@ -42,65 +40,60 @@ seconds after the 12th hour of June 26th, 2021 in UTC.
 The relative time offset can be formated as a time duration string with the
 following units: y, w, d, h, m, s. Negative offsets are also allowed. For
 example, -1h indicates the time of tool invocation minus one hour. Note that
-\--not-after is relative to the current time if a relative time offset is used,
-and not to \--not-before.
+--not-after is relative to the current time if a relative time offset is used,
+and not to --not-before.
 
-The <subject-template> is the template for the distinguished name of the
-requested certificate and must either be a x.509 certificate or a JSON file.
-The common name can be overridden by supplying the \--common-name flag.
+The subject-template is the template for the distinguished name of the requested
+certificate and must either be a x.509 certificate or a JSON file.
+The common name can be overridden by supplying the --common-name flag.
 
 If it is a x.509 certificate, the subject of the template is used as the subject
 of the created certificate or certificate chain request.
 
-A valid example for a JSON formatted template::
+A valid example for a JSON formatted template:
 
-  {
-    "common_name": "1-ff00:0:110 AS certificate",
-    "country": "CH",
-    "isd_as": "1-ff00:0:110"
-  }
+    {
+      "common_name": "1-ff00:0:110 AS certificate",
+      "country": "CH",
+      "isd_as": "1-ff00:0:110"
+    }
 
 All configurable fields with their type are defined by the following JSON
-schema::
-
-  {
-    "type": "object",
-    "properties": {
-      "isd_as":              { "type": "string" },
-      "common_name":         { "type": "string" },
-      "country":             { "type": "string" },
-      "locality":            { "type": "string" },
-      "organization":        { "type": "string" },
-      "organizational_unit": { "type": "string" },
-      "postal_code":         { "type": "string" },
-      "province":            { "type": "string" },
-      "serial_number":       { "type": "string" },
-      "street_address":      { "type": "string" },
-    },
-    "required": ["isd_as"]
-  }
-
-For more information on JSON schemas, see https://json-schema.org/.
-
-
-::
-
-  scion-pki certificate create [flags] <subject-template> <cert-file> <key-file>
-
-Examples
-~~~~~~~~
-
-::
-
-    scion-pki certificate create --profile cp-root subject.tmpl cp-root.crt cp-root.key
-    scion-pki certificate create --ca cp-ca.crt --ca-key cp-ca.key subject.tmpl chain.pem cp-as.key
-    scion-pki certificate create --csr subject.tmpl chain.csr cp-as.key
-
-Options
-~~~~~~~
-
-::
-
+schema:
+
+    {
+      "type": "object",
+      "properties": {
+        "isd_as":              { "type": "string" },
+        "common_name":         { "type": "string" },
+        "country":             { "type": "string" },
+        "locality":            { "type": "string" },
+        "organization":        { "type": "string" },
+        "organizational_unit": { "type": "string" },
+        "postal_code":         { "type": "string" },
+        "province":            { "type": "string" },
+        "serial_number":       { "type": "string" },
+        "street_address":      { "type": "string" },
+      },
+      "required": ["isd_as"]
+    }
+
+For more information on JSON schemas, see <https://json-schema.org/>.
+
+
+```
+scion-pki certificate create [flags] <subject-template> <cert-file> <key-file>
+```
+## Examples
+
+```
+  scion-pki certificate create --profile cp-root subject.tmpl cp-root.crt cp-root.key
+  scion-pki certificate create --ca cp-ca.crt --ca-key cp-ca.key subject.tmpl chain.pem cp-as.key
+  scion-pki certificate create --csr subject.tmpl chain.csr cp-as.key
+```
+## Options
+
+```
       --bundle               Bundle the certificate with the issuer certificate as a certificate chain
       --ca string            The path to the issuer certificate
       --ca-key string        The path to the issuer private key used to sign the new certificate
@@ -121,9 +114,8 @@ Options
                              timestamp or a unix timestamp. If the value is a duration, it is used as the
                              offset from the current time. (default 0s)
       --profile string       The type of certificate to generate (cp-as|cp-ca|cp-root|sensitive-voting|regular-voting) (default "cp-as")
+```
+## SEE ALSO
 
-SEE ALSO
-~~~~~~~~
-
-* :ref:`scion-pki certificate <scion-pki_certificate>` 	 - Manage certificates for the SCION control plane PKI.
+* [scion-pki certificate](scion-pki_certificate.md)	 - Manage certificates for the SCION control plane PKI.
 

doc/command/scion-pki/scion-pki_certificate_fingerprint.md

@@ -0,0 +1,41 @@
+---
+orphan: true
+---
+
+(app-scion-pki-certificate-fingerprint)=
+
+# scion-pki certificate fingerprint
+
+Calculate the SHA256 fingerprint of a certificate or certificate chain
+## Synopsis
+
+'fingerprint' computes the SHA256 fingerprint of the raw certificate or
+certificate chain.
+
+If 'cert-file' contains a single certificate, the SHA256 is computed over the raw
+DER encoding. If it contains a certificate chain, the SHA256 is computed over the
+concatenation of the raw DER encoding of the certificates in order of appearance.
+
+If the flag --format is set to "emoji", the format of the output is a string of emojis
+
+```
+scion-pki certificate fingerprint [flags] <cert-file>
+```
+## Examples
+
+```
+  scion-pki certificate fingerprint ISD1-ASff00_0_110.pem
+  scion-pki certificate fingerprint --format emoji ISD1-ASff00_0_110.pem
+  scion-pki certificate fingerprint --format hex ISD1-ASff00_0_110.pem
+
+```
+## Options
+
+```
+      --format string   The format of the fingerprint (hex|base64|base64-url|base64-raw|base64-url-raw|emoji). (default "hex")
+  -h, --help            help for fingerprint
+```
+## SEE ALSO
+
+* [scion-pki certificate](scion-pki_certificate.md)	 - Manage certificates for the SCION control plane PKI.
+