From 0affc2619864a59e9b68873713dc0a2dfeb1fabf Mon Sep 17 00:00:00 2001 From: Vo Minh Thu Date: Wed, 26 Jun 2024 15:32:23 +0200 Subject: [PATCH] Add some module descriptions. --- default.nix | 1 + scripts/serve-haddock.sh | 7 +++++++ slab.cabal | 2 +- src/Slab/Build.hs | 10 ++++++++++ src/Slab/Error.hs | 7 +++++++ src/Slab/Evaluate.hs | 14 ++++++++++++++ src/Slab/Execute.hs | 10 ++++++++++ src/Slab/Generate/Haskell.hs | 8 ++++++++ src/Slab/Parse.hs | 8 ++++++++ src/Slab/PreProcess.hs | 7 +++++++ src/Slab/Render.hs | 6 ++++++ src/Slab/Report.hs | 7 +++++++ src/Slab/Serve.hs | 6 ++++++ src/Slab/Syntax.hs | 6 ++++++ src/Slab/Watch.hs | 6 ++++++ 15 files changed, 104 insertions(+), 1 deletion(-) create mode 100755 scripts/serve-haddock.sh diff --git a/default.nix b/default.nix index ac8746f..5b27841 100644 --- a/default.nix +++ b/default.nix @@ -6,6 +6,7 @@ in rec { # Build with nix-build -A binaries = nixpkgs.haskellPackages.slab; + haddock = nixpkgs.haskellPackages.slab.doc; # A shell to try out our binaries # Run with nix-shell default.nix -A shell diff --git a/scripts/serve-haddock.sh b/scripts/serve-haddock.sh new file mode 100755 index 0000000..31a823c --- /dev/null +++ b/scripts/serve-haddock.sh @@ -0,0 +1,7 @@ +#! /usr/bin/env nix-shell +#! nix-shell -i bash -p busybox + +HADDOCK_DIR=$(nix-build -A haddock ./default.nix --no-out-link) + +echo "Visit http://127.0.0.1:9000/" +httpd -f -p 9000 -h "${HADDOCK_DIR}/share/doc/slab-0.0.2.0/html/" diff --git a/slab.cabal b/slab.cabal index abcaba7..8cc075c 100644 --- a/slab.cabal +++ b/slab.cabal @@ -11,7 +11,7 @@ synopsis: A programmable markup language to generate HTML description: Slab is an alternative syntax for writing HTML, plus some programming language features (often found in templating languages, like conditionals - and loops). + and loops). You can visit the project homepage at . category: text source-repository head diff --git a/src/Slab/Build.hs b/src/Slab/Build.hs index 8354dbc..3cf87e5 100644 --- a/src/Slab/Build.hs +++ b/src/Slab/Build.hs @@ -1,3 +1,13 @@ +-- | +-- Module : Slab.Build +-- Description : Build Slab templates to HTML +-- +-- @Slab.Build@ provides types and functions to easily build Slab templates. +-- There are mostly two ways to build templates: by writing the resulting HTML +-- to files, or by writing them to an @STM@-based store. +-- +-- Writing to disk is used by the @slab watch@ command. Writing to the @STM@ +-- store is used by the @slab serve@ command. module Slab.Build ( buildDir , buildFile diff --git a/src/Slab/Error.hs b/src/Slab/Error.hs index aa0416a..03ae1a2 100644 --- a/src/Slab/Error.hs +++ b/src/Slab/Error.hs @@ -1,3 +1,10 @@ +-- | +-- Module : Slab.Error +-- Description : Errors that the different Slab stages can produce +-- +-- @Slab.Error@ provides a data type to represent all the errors emitted by +-- Slab. It also provides helper functions to report errors in a human-readable +-- way. module Slab.Error ( Error (..) , unwrap diff --git a/src/Slab/Evaluate.hs b/src/Slab/Evaluate.hs index 5be3811..d64d9a3 100644 --- a/src/Slab/Evaluate.hs +++ b/src/Slab/Evaluate.hs @@ -1,5 +1,19 @@ {-# LANGUAGE RecordWildCards #-} +-- | +-- Module : Slab.Evaluate +-- Description : Evaluate an AST (to a non-reducible AST) +-- +-- @Slab.Evaluate@ implements the evaluation stage of Slab, following both the +-- parsing and pre-processing stages. This is responsible of reducing for +-- instance @1 + 2@ to @3@, or transforming a loop construct to an actual list +-- of HTML blocks. +-- +-- Evaluation works on an abstract syntax tree (defined in "Slab.Syntax") and +-- currently reuses the sames types for its result. +-- +-- The stage following evaluation is "Slab.Execute", responsible of running +-- external commands. module Slab.Evaluate ( evaluateFile , evaluate diff --git a/src/Slab/Execute.hs b/src/Slab/Execute.hs index f10b7b4..864e928 100644 --- a/src/Slab/Execute.hs +++ b/src/Slab/Execute.hs @@ -1,6 +1,16 @@ {-# LANGUAGE MultiWayIf #-} {-# LANGUAGE RecordWildCards #-} +-- | +-- Module : Slab.Execute +-- Description : Run external commands referenced by an AST +-- +-- @Slab.Execute@ implements the execution stage of Slab, i.e. running external +-- commands (for instance referenced by the @run@ syntax). This is done after +-- the evaluation stage (implemented in "Slab.Evaluate"). +-- +-- After execution, the resulting blocks can be rendered to HTML by +-- "Slab.Render". module Slab.Execute ( executeFile , execute diff --git a/src/Slab/Generate/Haskell.hs b/src/Slab/Generate/Haskell.hs index b4161ed..fd489a3 100644 --- a/src/Slab/Generate/Haskell.hs +++ b/src/Slab/Generate/Haskell.hs @@ -1,3 +1,11 @@ +-- | +-- Module : Slab.Generate.Haskell +-- Description : Translate from the Slab syntax to Haskell +-- +-- @Slab.Generate.Haskell@ is an attempt to translate Slab to Haskell. This +-- could make it possible to use Slab within Haskell projects without needing +-- to interpret Slab templates at runtime. If this proves useful, other +-- languages could also be supported. module Slab.Generate.Haskell ( renderHs ) where diff --git a/src/Slab/Parse.hs b/src/Slab/Parse.hs index 977af2c..6a1c027 100644 --- a/src/Slab/Parse.hs +++ b/src/Slab/Parse.hs @@ -1,5 +1,13 @@ {-# LANGUAGE RecordWildCards #-} +-- | +-- Module : Slab.Parse +-- Description : Parse the concrete Slab syntax to an AST +-- +-- @Slab.Parse@ provides parsers to read text and construct an abstract syntax +-- tree, as represented by "Slab.Syntax". +-- +-- Parsers are written using the @megaparsec@ library. module Slab.Parse ( parseFile , parseFileE diff --git a/src/Slab/PreProcess.hs b/src/Slab/PreProcess.hs index 8d620f5..ec84c87 100644 --- a/src/Slab/PreProcess.hs +++ b/src/Slab/PreProcess.hs @@ -1,6 +1,13 @@ {-# LANGUAGE MultiWayIf #-} {-# LANGUAGE RecordWildCards #-} +-- | +-- Module : Slab.PreProcess +-- Description : Parse and process included and imported files +-- +-- @Slab.PreProcess@ recursively parses files, following includes and imports. +-- This is also responsible of reading JSON files referenced in the expression +-- language. module Slab.PreProcess ( Context (..) , preprocessFile diff --git a/src/Slab/Render.hs b/src/Slab/Render.hs index 084d428..d159cc8 100644 --- a/src/Slab/Render.hs +++ b/src/Slab/Render.hs @@ -1,3 +1,9 @@ +-- | +-- Module : Slab.Render +-- Description : Render an AST to HTML +-- +-- @Slab.Render@ transforms an evaluated syntax tree to HTML. In practice this +-- can be @blaze-html@'s @Html@, or @Text@ and lazy @ByteString@. module Slab.Render ( prettyHtmls , renderHtmls diff --git a/src/Slab/Report.hs b/src/Slab/Report.hs index 9e8b487..75cbaec 100644 --- a/src/Slab/Report.hs +++ b/src/Slab/Report.hs @@ -1,3 +1,9 @@ +-- | +-- Module : Slab.Report +-- Description : Report information about Slab templates (mostly empty for now) +-- +-- This module serves as a way to explore new Slab features, e.g. creating a +-- module system, or analyzing a growing HTML code base to help refactor it. module Slab.Report ( run ) where @@ -28,6 +34,7 @@ isPage _ = False -------------------------------------------------------------------------------- -- Similar to Build.buildDir and buildFile, but don't render HTML to disk. +-- TODO Move this code to (and combine it with) with @Slab.Build@. buildDir :: FilePath -> IO [Module] buildDir srcDir = do diff --git a/src/Slab/Serve.hs b/src/Slab/Serve.hs index 04add25..618c10b 100644 --- a/src/Slab/Serve.hs +++ b/src/Slab/Serve.hs @@ -2,6 +2,12 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE NoImplicitPrelude #-} +-- | +-- Module : Slab.Serve +-- Description : Run a development server to preview Slab templates +-- +-- @Slab.Serve@ watches a set of Slab templates, continuously rebuilding them +-- as they change, and runs a web server to serve them. module Slab.Serve ( run ) where diff --git a/src/Slab/Syntax.hs b/src/Slab/Syntax.hs index 6101f05..5fedd02 100644 --- a/src/Slab/Syntax.hs +++ b/src/Slab/Syntax.hs @@ -1,5 +1,11 @@ {-# LANGUAGE RecordWildCards #-} +-- | +-- Module : Slab.Syntax +-- Description : The abstract syntax used by Slab +-- +-- @Slab.Syntax@ provides data types to represent the syntax used by the Slab +-- language. It also provides small helpers functions to operate on the syntax. module Slab.Syntax ( Block (..) , isDoctype diff --git a/src/Slab/Watch.hs b/src/Slab/Watch.hs index 5d93b87..eaf7648 100644 --- a/src/Slab/Watch.hs +++ b/src/Slab/Watch.hs @@ -1,3 +1,9 @@ +-- | +-- Module : Slab.Watch +-- Description : Continuously build a set of Slab templates +-- +-- @Slab.Watch@ watches a set of Slab templates, continuously rebuilding them +-- as they change. module Slab.Watch ( run ) where