Extend sphinx documentation

docs/source/conf.py

@@ -15,7 +15,10 @@ release = latest_tag
 version = release
 
 myst_substitutions = {
-  "repo_host" : "codeberg.org" # or 'github.com'
+  "repo_host" : "codeberg.org", # or 'github.com'
+#  "repo_host" : "github.com",
+  "repo_pgpainless_src" : "codeberg.org/pgpainless/pgpainless/src/branch",
+#  "repo_pgpainless_src" : "github.com/pgpainless/pgpainless/tree",
 }
 
 # -- General configuration

docs/source/pgpainless-core/quickstart.md

@@ -1,31 +1,125 @@
 ## PGPainless API with pgpainless-core
 
-Coming soon.
+The `pgpainless-core` module contains the bulk of the actual OpenPGP implementation.
 
 :::{note}
 This chapter is work in progress.
 :::
 
 ### Setup
-bla
+
+PGPainless' releases are published to and can be fetched from Maven Central.
+To get started, you first need to include `pgpainless-core` in your projects build script:
+
+```
+// If you use Gradle
+...
+dependencies {
+    ...
+    implementation "org.pgpainless:pgpainless-core:XYZ"
+    ...
+}
+
+// If you use Maven
+...
+<dependencies>
+    ...
+    <dependency>
+        <groupId>org.pgpainless</groupId>
+        <artifactId>pgpainless-core</artifactId>
+        <version>XYZ</version>
+    </dependency>
+    ...
+</dependencies>
+```
+
+This will automatically pull in PGPainless' dependencies, such as Bouncy Castle.
+
+:::{important}
+Replace `XYZ` with the current version, in this case {{ env.config.version }}!
+:::
+
+The entry point to the API is the `PGPainless` class.
+For many common use-cases, examples can be found in the
+{{ '[examples package](https://{}/main/pgpainless-core/src/test/java/org/pgpainless/example)'.format(repo_pgpainless_src) }}.
+There is a very good chance that you can find code examples there that fit your needs.
+
+### Read and Write Keys
+Reading keys from ASCII armored strings or from binary files is easy:
+
+```java
+String key = "-----BEGIN PGP PRIVATE KEY BLOCK-----\n"...;
+PGPSecretKeyRing secretKey = PGPainless.readKeyRing()
+        .secretKeyRing(key);
+```
+
+Similarly, keys or certificates can quickly be exported:
+
+```java
+// ASCII armored key
+PGPSecretKeyRing secretKey = ...;
+String armored = PGPainless.asciiArmor(secretKey);
+        
+// binary (unarmored) key
+byte[] binary = secretKey.getEncoded();
+```
 
 ### Generate a Key
-bla
+PGPainless comes with a simple to use `KeyRingBuilder` class that helps you to quickly generate modern OpenPGP keys.
+There are some predefined key archetypes, but it is possible to fully customize the key generation to fit your needs.
+
+```java
+// EdDSA primary key with EdDSA signing- and XDH encryption subkeys
+PGPSecretKeyRing secretKeys = PGPainless.generateKeyRing()
+        .modernKeyRing("Romeo <romeo@montague.lit>", "thisIsAPassword");
+
+// RSA key without additional subkeys
+PGPSecretKeyRing secretKeys = PGPainless.generateKeyRing()
+        .simpleRsaKeyRing("Juliet <juliet@montague.lit>", RsaLength._4096);
+```
+
+To generate a customized key, use `PGPainless.buildKeyRing()` instead:
+
+```java
+// Customized key
+PGPSecretKeyRing keyRing = PGPainless.buildKeyRing()
+        .setPrimaryKey(KeySpec.getBuilder(
+                RSA.withLength(RsaLength._8192),
+                KeyFlag.SIGN_DATA, KeyFlag.CERTIFY_OTHER)
+                        .overrideCompressionAlgorithms(CompressionAlgorithm.ZLIB)
+        ).addSubkey(
+                KeySpec.getBuilder(ECDSA.fromCurve(EllipticCurve._P256), KeyFlag.SIGN_DATA)
+        ).addSubkey(
+                KeySpec.getBuilder(
+                        ECDH.fromCurve(EllipticCurve._P256),
+                        KeyFlag.ENCRYPT_COMMS, KeyFlag.ENCRYPT_STORAGE)
+        ).addUserId("Juliet <juliet@montague.lit>")
+        .addUserId("xmpp:juliet@capulet.lit")
+        .setPassphrase(Passphrase.fromPassword("romeo_oh_Romeo<3"))
+        .build();
+```
+
+As you can see, it is possible to generate all kinds of different keys.
 
 ### Extract a Certificate
-bla
+If you have a secret key, you might want to extract a public key certificate from it:
+
+```java
+PGPSecretKeyRing secretKey = ...;
+PGPPublicKeyRing certificate = PGPainless.extractCertificate(secretKey);
+```
 
 ### Apply / Remove ASCII Armor
-bla
+TODO
 
 ### Encrypt a Message
-bla
+TODO
 
 ### Decrypt a Message
-bla
+TODO
 
 ### Sign a Message
-bla
+TODO
 
 ### Verify a Signature
-bla
+TODO

docs/source/pgpainless-sop/quickstart.md

@@ -239,7 +239,7 @@ If you provided the senders certificate for the purpose of signature verificatio
 probably want to check, if the message was actually signed by the sender by checking `result.getVerifications()`.
 
 :::{note}
-Signature verification will be discussed in more detail in section [](#verifications)
+Signature verification will be discussed in more detail in section "Verifications".
 :::
 
 If the message was encrypted symmetrically using a password, you can also decrypt is symmetrically by calling