diff --git a/.gitignore b/.gitignore index 7fea862..91ef75e 100644 --- a/.gitignore +++ b/.gitignore @@ -30,5 +30,5 @@ replay_pid* # Temporary output directories **/target -# Maven Central Repo settings -settings.xml +# Doc output directory +_site diff --git a/bitbadger-doc.png b/bitbadger-doc.png new file mode 100644 index 0000000..22b1fe2 Binary files /dev/null and b/bitbadger-doc.png differ diff --git a/doc-template/public/main.css b/doc-template/public/main.css new file mode 100644 index 0000000..cfa8c03 --- /dev/null +++ b/doc-template/public/main.css @@ -0,0 +1,4 @@ +article h2 { + border-bottom: solid 1px gray; + margin-bottom: 1rem; +} diff --git a/doc-template/public/main.js b/doc-template/public/main.js new file mode 100644 index 0000000..264108e --- /dev/null +++ b/doc-template/public/main.js @@ -0,0 +1,10 @@ +export default { + defaultTheme: "auto", + iconLinks: [ + { + icon: "git", + href: "https://git.bitbadger.solutions/bit-badger/solutions.bitbadger.documents", + title: "Source Repository" + } + ] +} \ No newline at end of file diff --git a/docfx.json b/docfx.json new file mode 100644 index 0000000..b7f907b --- /dev/null +++ b/docfx.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json", + "build": { + "content": [ + { + "files": [ + "**/*.{md,yml}" + ], + "exclude": [ + "_site/**" + ] + } + ], + "resource": [ + { + "files": [ + "images/**", + "bitbadger-doc.png", + "favicon.ico" + ] + } + ], + "output": "_site", + "template": [ + "default", + "modern", + "doc-template" + ], + "globalMetadata": { + "_appName": "solutions.bitbadger.documents", + "_appTitle": "solutions.bitbadger.documents", + "_appLogoPath": "bitbadger-doc.png", + "_appFaviconPath": "favicon.ico", + "_appFooter": "Hand-crafted documentation created with docfx by Bit Badger Solutions", + "_enableSearch": true, + "pdf": false + } + } +} \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..1900b27 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,17 @@ +# Getting Started + +The exceedingly quick version: + +- Add the desired module/package to your dependencies +- Implement an instance of the `DocumentSerializer` interface and assign it to the `DocumentConfig.serializer` property (for all but kotlinx) +- Set a PostgreSQL or SQLite JDBC connection string for the `Configuration.connectionString` property + +At this point, `Connection.dbConn()` will provide a connection which can be used either for function calls or extension method calls. You will also be able to call functions without providing a connection, and the library will create one for that command. (Database pooling will help reduce connection overhead when using this technique.) + +From there, `Definition.ensureTable(name)` will create a table, and you are ready to start manipulating documents! + +(Documentation is in active development; until it is more complete, the flow is very similar to [BitBadger.Documents](https://bitbadger.solutions/open-source/relational-documents/dotnet/basic-usage.html), the .NET implementation of a similar library. This library also supports `Json` in place of `Find` to return raw JSON, and `Json.write*` to write that JSON to a `PrintWriter`, bypassing the entire deserialize-from-the-database, serialize-to-the-output-body process.) + +## Examples + +Each library has an exhaustive suite of integration tests; reviewing those may also provide insight into the patterns used for effective document storage and retrieval. diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 0000000..6c61598 --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,2 @@ +- name: Getting Started + href: getting-started.md \ No newline at end of file diff --git a/favicon.ico b/favicon.ico new file mode 100644 index 0000000..22ca446 Binary files /dev/null and b/favicon.ico differ diff --git a/index.md b/index.md new file mode 100644 index 0000000..511c427 --- /dev/null +++ b/index.md @@ -0,0 +1,41 @@ +--- +_layout: landing +--- + +Welcome! This project implements the [relational document](/) concepts for Java, Kotlin, Scala, and Groovy applications. + +## Modules + +The coordinate structure for these packages is +```xml +solutions.bitbadger.documents +[package] +1.0.0-RC1 +``` + +### solutions.bitbadger.documents.core + +![Maven Central Version](https://img.shields.io/maven-central/v/solutions.bitbadger.documents/core) + +This module does most of the heavy lifting for all languages. It provides an optimal Java experience and an optimal Kotlin experience when using a reflection-based JSON serializer. Queries that can return one-or-none return an `Optional` instance. This module also has Kotlin extensions on the JDBC `Connection` type + +### solutions.bitbadger.documents.groovy + +![Maven Central Version](https://img.shields.io/maven-central/v/solutions.bitbadger.documents/groovy) + +This far-out module provides Groovy-style extension methods on the `Connection` type. (Right on!) + +### solutions.bitbadger.documents.scala + +![Maven Central Version](https://img.shields.io/maven-central/v/solutions.bitbadger.documents/scala) + +This module provides a native Scala API for this library, using its collection types instead of the default Java collections, and returns the Scala `Option[A]` type for one-or-none queries. It also provides Scala extension methods for the `Connection` type. + +### solutions.bitbadger.documents.kotlinx + +![Maven Central Version](https://img.shields.io/maven-central/v/solutions.bitbadger.documents/kotlinx) + +This module utilizes [`kotlix.serialization`][kotlinx] for its serialization and deserialization, which implements these actions without reflection. As its primary consumer is Kotlin, it returns `null` for one-or-none queries. + + +[kotlinx]: https://github.com/Kotlin/kotlinx.serialization "KotlinX Serialization • GitHub" diff --git a/toc.yml b/toc.yml new file mode 100644 index 0000000..4159304 --- /dev/null +++ b/toc.yml @@ -0,0 +1,2 @@ +- name: Docs + href: docs/ \ No newline at end of file