Add even more docs

README.md

@@ -1,25 +1,65 @@
-# gloss2
+# gloss
 
-[![Package Version](https://img.shields.io/hexpm/v/gloss2)](https://hex.pm/packages/gloss2)
-[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gloss2/)
+Gloss is a simple blog generator for Gleam, using [Lustre](https://hexdocs.pm/lustre) and
+[lustre_ssg](https://hexdocs.pm/lustre_ssg).
 
-```sh
-gleam add gloss2
+Gloss runs on the JavaScript target and it's tested with Node.js.
+
+<!-- [![Package Version](https://img.shields.io/hexpm/v/gloss)](https://hex.pm/packages/gloss) -->
+<!-- [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gloss/) -->
+
+## Quickstart
+
+Gloss is not yet available on Hex. You can use it with a path dependency instead. Create a new
+Gleam project and add the following to `gleam.toml`:
+
+```toml
+[dependencies]
+gleam_stdlib = "~> 0.36 or ~> 1.0"
+gloss = { path = "../path/to/gloss" }
 ```
+
+To generate a default blog, use the following in your main file:
+
 ```gleam
-import gloss2
+import gleam/result
+import gleam/option
+import gleam/io
+import gloss/builder
+import gloss/config.{type Configuration, Configuration}
+import gloss/defaults
 
 pub fn main() {
-  // TODO: An example of the project in use
+  let config =
+    defaults.default_config(
+      "My Blog",
+      "https://my.blog.example/",
+      "en",
+      config.Author(
+        "Person McPerson",
+        option.Some("person@example.com"),
+        option.Some("https://fedi.instance.example/@person"),
+      ),
+      "© Person McPerson",
+    )
+
+  io.debug(build(config))
+}
+
+pub fn build(config: Configuration) {
+  // Parse the files
+  use db <- result.try(builder.parse(config))
+  // Compile Markdown into HTML
+  let compiled = builder.compile(db, config)
+  // Render content into Lustre elements
+  let rendered = builder.render(db, compiled, config)
+  // Write rendered content into the filesystem
+  builder.write(rendered, config)
 }
 ```
 
-Further documentation can be found at <https://hexdocs.pm/gloss2>.
+## Documentation
 
-## Development
-
-```sh
-gleam run   # Run the project
-gleam test  # Run the tests
-gleam shell # Run an Erlang shell
-```
+- [Gloss Demo Blog](https://nicd.gitlab.io/gloss_blog)
+- [User's Guide](https://nicd.gitlab.io/gloss_blog/guide.html)
+- [Gloss API reference](https://nicd.gitlab.io/gloss)

src/gloss/config.gleam

@@ -41,7 +41,9 @@ pub type Views {
   Views(
     base: fn(Database, Configuration) -> BaseView,
     meta: fn(Database, Configuration) -> MetaView,
+    /// View for a single post that is rendered on its own.
     single_post_full: fn(Database, Configuration) -> SinglePostView,
+    /// View for a single post rendered as part of a list.
     single_post_list: fn(Database, Configuration) -> SinglePostView,
     page: fn(Database, Configuration) -> PageView,
     list_page: fn(Database, Configuration) -> ListPageView,

src/gloss/renderer.gleam

@@ -1,3 +1,6 @@
+//// The renderer's job is to render compiled content into HTML. By default this
+//// means Lustre elements that can be later stringified.
+
 import gleam/list
 import gleam/dict.{type Dict}
 import gleam/result
@@ -19,10 +22,12 @@ import gloss/utils/ordered_tree
 import gloss/config.{type Configuration}
 import gloss/utils/date
 
+/// Helper struct to pass all the used views to the rendering functions.
 pub type Views {
   Views(
     base: BaseView,
     meta: MetaView,
+    /// View for a single post rendered on its own.
     single_post_full: SinglePostView,
     page: PageView,
     list_page: ListPageView,
@@ -30,6 +35,7 @@ pub type Views {
   )
 }
 
+/// Render the database and compiled content using the configuration.
 pub fn render(
   db: Database,
   compiled: CompileDatabase,

src/gloss/writer.gleam

@@ -1,3 +1,5 @@
+//// The writer takes rendered content and writes it into the filesystem.
+
 import gleam/list
 import gleam/dict
 import gleam/result
@@ -9,6 +11,7 @@ import gloss/rendering/database.{type RenderDatabase} as _
 import gloss/config.{type Configuration, WriteError}
 import gloss/utils/priv
 
+/// Write the rendered content into the filesystem using lustre_ssg.
 pub fn write(db: RenderDatabase, config: Configuration) {
   let site =
     ssg.new(config.output_path)

src/lustre/ssg/atom.gleam

@@ -1,3 +1,5 @@
+//// Bindings for Atom feed elements.
+
 import lustre/element.{type Element, advanced, element, namespaced, text}
 import lustre/attribute.{attribute}
 

src/lustre/ssg/xml.gleam

@@ -1,5 +1,6 @@
 import lustre/element.{advanced}
 
+/// Generate an XML declaration.
 pub fn declaration() {
   advanced("", "?xml version=\"1.0\" encoding=\"utf-8\"?", [], [], False, True)
 }