Merge pull request #294 from dahlia/docs

Build the nirum.org website using docs target

Author: dahlia

.travis.yml

@@ -126,6 +126,9 @@ script:
 - 'TOX="$(python3 -m site --user-base)/bin/tox" stack --no-terminal test -j4 --coverage'
 - ./lint.sh
 
+# Build website
+- stack runhaskell ./app/nirum-docs.hs /tmp/nirum.org/
+
 after_script:
 - |
   # Since codecov-haskell doesn't work on Windows,
@@ -142,6 +145,11 @@ after_script:
     --token="$(echo $token_encoded | python -m base64 -d)" \
     spec
 
+# Used for making a commit into gh-pages (nirum.org website)
+- git log -n1 --format="format:%s%n%n$TRAVIS_COMMIT_RANGE" > /tmp/git-commit
+- git log -n1 --format="format:%an" > /tmp/git-author
+- git log -n1 --format="format:%ae" > /tmp/git-author-email
+
 notifications:
   webhooks:
     urls:
@@ -235,3 +243,20 @@ after_deploy: |
     python -c 'import json, os; print(json.dumps({"username": os.environ["HACKAGE_USERNAME"], "password": os.environ["HACKAGE_PASSWORD"]}))' > ~/.stack/upload/credentials.json
     stack --no-terminal upload --ignore-check --no-signature .
   fi
+
+  # Upload website to nirum.org
+  echo "$NIRUM_GH_PAGES_KEY" | tr / '\n' > /tmp/nirum_org_ed25519
+  chmod 600 /tmp/nirum_org_ed25519
+  eval "$(ssh-agent -s)"
+  ssh-add /tmp/nirum_org_ed25519
+  pushd /tmp/nirum.org/
+  git init
+  git config user.name "$(cat /tmp/git-author)"
+  git config user.email "$(cat /tmp/git-author-email)"
+  echo nirum.org > CNAME
+  touch .nojekyll
+  git add .
+  git commit -a -F /tmp/git-commit
+  git push -f [email protected]:nirum-lang/nirum-lang.github.io.git master
+  popd
+  rm /tmp/nirum_org_ed25519

CHANGES.md

@@ -20,6 +20,8 @@ To be released.
  -  [CommonMark] in docstrings became to have a limited subset of
     [special attributes extension].  It's only allowed to heading elements and
     only anchor identifiers are supported (e.g., `{#header-id}`).
+ -  `style`, `header`, and `footer` options were added.  These options purpose
+    to customize the look and feel of the result pages.
  -  Fixed an incorrect processing of [CommonMark] thight list items: it had
     crashed when a thight list item contains blocks other than paragraphs.
 

app/nirum-docs.hs

@@ -0,0 +1,88 @@
+#!/usr/bin/env stack runghc
+{-# LANGUAGE OverloadedLists #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE QuasiQuotes #-}
+import Control.Monad
+import Data.List (isPrefixOf)
+import System.Environment
+
+import Data.Map.Strict
+import Data.Set
+import Data.Text hiding (isPrefixOf)
+import System.FilePath (pathSeparator)
+import Text.InterpolatedString.Perl6 (q)
+
+import Nirum.Cli (writeFiles)
+import Nirum.Constructs.Module
+import Nirum.Package
+import Nirum.Targets
+import Nirum.Targets.Docs (Docs (..))
+import Nirum.Package.Metadata
+import Nirum.Package.ModuleSet
+import qualified Nirum.Version
+
+packageMetadata :: Metadata Docs
+packageMetadata = Metadata
+    { version = Nirum.Version.version
+    , description = Just
+        "IDL compiler and RPC/distributed object framework for microservices"
+    , license = Just "GPL-3"
+    , keywords = ["IDL", "microservices", "SOA", "RPC"]
+    , authors = [Author "Nirum team" Nothing Nothing]
+    , Nirum.Package.Metadata.target = Docs
+        { docsTitle = "Nirum"
+        , docsStyle = style
+        , docsHeader = ""
+        , docsFooter = footer
+        }
+    }
+
+loadPackage :: FilePath -> IO (Either (Set ImportError) (Package Docs))
+loadPackage path = do
+    documents <- filterWithKey ignores <$> scanDocuments path
+    return $ case fromMap [(coreModulePath, coreModule)] of
+        Left importErrors -> Left importErrors
+        Right ms -> Right $ Package packageMetadata ms documents
+  where
+    ignores :: FilePath -> d -> Bool
+    ignores filePath _ =
+        not $ ("examples" ++ [pathSeparator]) `isPrefixOf` filePath
+
+main :: IO ()
+main = do
+    args <- getArgs
+    outputDir <- case args of
+        o : _ -> return o
+        [] -> fail "missing output path"
+    packageR <- loadPackage "."
+    package <- case packageR of
+        Left errors -> fail (show errors)
+        Right p -> return p
+    case buildPackage package of
+        Right buildResult -> writeFiles outputDir buildResult
+        Left e -> print e
+
+style :: Text
+style = [q|
+.github-corner:hover .octo-arm {
+    animation: octocat-wave 560ms ease-in-out;
+}
+@keyframes octocat-wave {
+    0%, 100% { transform:rotate(0) }
+    20%, 60% { transform:rotate(-25deg) }
+    40%, 80% { transform:rotate(10deg) }
+}
+@media (max-width:500px) {
+    .github-corner:hover .octo-arm {
+        animation: none;
+    }
+    .github-corner .octo-arm {
+        animation: octocat-wave 560ms ease-in-out;
+    }
+}
+|]
+
+footer :: Text
+footer = [q|
+<div class="github"><a href="https://github.com/spoqa/nirum/tree/master/examples" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a></div>
+|]

docs/target/docs.md

@@ -2,8 +2,10 @@ Docs target
 ===========
 
 This target does not generate any program code files, but HTML pages (and
-some extra assets like CSS).  It generates two kinds of pages:
+some extra assets like CSS).  It generates three kinds of pages:
 
+ -  A home page that renders *README.md* file (if exists) or table of contents
+    (if there is no *README.md* file).
  -  Reference docs from the docs comments in the source code: type definitions,
     union tags, enum members, service methods, etc, and
  -  Manual pages from CommonMark (i.e., _\*.md_) files.
@@ -42,3 +44,15 @@ Settings
 
 It goes to `<title>` elements of generated HTML pages.  It's usually a name of
 the Nirum package.
+
+
+### `style` (optional): Custom CSS
+
+It goes to very ending of the CSS file, which means it can override other
+predefined style rules.
+
+
+### `header`/`footer` (optional): Custom header & footer HTML
+
+It goes to the very beginning and ending of `<body>` contents.  It's usually
+used to customize HTML pages.

examples/package.toml

@@ -10,3 +10,24 @@ classifiers = [
 
 [targets.docs]
 title = "Nirum Examples"
+style = """
+.github-corner:hover .octo-arm {
+    animation: octocat-wave 560ms ease-in-out;
+}
+@keyframes octocat-wave {
+    0%, 100% { transform:rotate(0) }
+    20%, 60% { transform:rotate(-25deg) }
+    40%, 80% { transform:rotate(10deg) }
+}
+@media (max-width:500px) {
+    .github-corner:hover .octo-arm {
+        animation: none;
+    }
+    .github-corner .octo-arm {
+        animation: octocat-wave 560ms ease-in-out;
+    }
+}
+"""
+footer = """
+<div class="github"><a href="https://github.com/spoqa/nirum/tree/master/examples" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a></div>
+"""

src/Nirum/Cli.hs

@@ -37,11 +37,12 @@ import Nirum.Package.ModuleSet ( ImportError ( CircularImportError
                                              , MissingModulePathError
                                              )
                                )
-import Nirum.Targets ( BuildError (CompileError, PackageError, TargetNameError)
-                     , BuildResult
-                     , buildPackage
-                     , targetNames
-                     )
+import Nirum.Targets
+    ( BuildError (..)
+    , BuildResult
+    , buildPackageFromFilePath
+    , targetNames
+    )
 import Nirum.Version (versionString)
 
 type TFlag = TVar Bool
@@ -136,7 +137,7 @@ build options@AppOptions { packagePath = src
                          , outputPath = outDir
                          , targetLanguage = target
                          } = do
-    result <- buildPackage target src
+    result <- buildPackageFromFilePath target src
     case result of
         Left (TargetNameError targetName') ->
             tryDie' [qq|Couldn't find "$targetName'" target.

src/Nirum/Package/Metadata.hs

@@ -40,6 +40,7 @@ module Nirum.Package.Metadata ( Author (Author, email, name, uri)
                               , fieldType
                               , metadataFilename
                               , metadataPath
+                              , optional
                               , parseMetadata
                               , packageTarget
                               , prependMetadataErrorField

src/Nirum/Targets.hs

@@ -1,11 +1,13 @@
 {-# LANGUAGE QuasiQuotes, ScopedTypeVariables, TemplateHaskell #-}
-module Nirum.Targets ( BuildError (CompileError, PackageError, TargetNameError)
-                     , BuildResult
-                     , Target (..)
-                     , TargetName
-                     , buildPackage
-                     , targetNames
-                     ) where
+module Nirum.Targets
+    ( BuildError (..)
+    , BuildResult
+    , Target (..)
+    , TargetName
+    , buildPackage
+    , buildPackageFromFilePath
+    , targetNames
+    ) where
 
 import Data.Either (partitionEithers)
 import Data.Maybe (fromMaybe)
@@ -48,34 +50,41 @@ type BuildResult = M.Map FilePath ByteString
 
 packageBuilders :: M.Map TargetName
                          (FilePath -> IO (Either BuildError BuildResult))
-packageBuilders = M.fromList $(targetProxyMapQ [e|buildPackage'|])
+packageBuilders = M.fromList $(targetProxyMapQ [e|buildPackageFromFilePath'|])
 
 targetNames :: Set TargetName
 targetNames = M.keysSet packageBuilders
 
-buildPackage :: TargetName -> FilePath -> IO (Either BuildError BuildResult)
-buildPackage targetName' =
+buildPackage :: forall t. Target t => Package t -> Either BuildError BuildResult
+buildPackage pkg@Package { metadata = Metadata { target = target' } } =
+    case partitionEithers eithers of
+        (errors@(_ : _), _) ->
+            Left $ CompileError $ M.fromList errors
+        ([], outs) -> Right $ M.fromList outs
+  where
+    results :: [(FilePath, Either (CompileError t) (CompileResult t))]
+    results = M.toList $ compilePackage pkg
+    eithers :: [Either (FilePath, Text) (FilePath, ByteString)]
+    eithers = [ case result of
+                    Left e -> Left (f, showCompileError target' e)
+                    Right r -> Right (f, toByteString target' r)
+              | (f, result) <- results
+              ]
+
+buildPackageFromFilePath :: TargetName
+                         -> FilePath
+                         -> IO (Either BuildError BuildResult)
+buildPackageFromFilePath targetName' =
     fromMaybe (\ _ -> return $ Left $ TargetNameError targetName') $
               M.lookup targetName' packageBuilders
 
-buildPackage' :: forall t. Target t
-              => Proxy t
-              -> FilePath
-              -> IO (Either BuildError BuildResult)
-buildPackage' _ packagePath = do
+buildPackageFromFilePath' :: forall t. Target t
+                          => Proxy t
+                          -> FilePath
+                          -> IO (Either BuildError BuildResult)
+buildPackageFromFilePath' _ packagePath = do
     scanResult <- scanPackage packagePath
     return $ case scanResult of
         Left e -> Left $ PackageError e
         Right (pkg :: Package t) ->
-            let Package { metadata = Metadata { target = target' } } = pkg
-                results = M.toList $ compilePackage pkg
-                eithers = [ case result of
-                                Left e -> Left (f, showCompileError target' e)
-                                Right r -> Right (f, toByteString target' r)
-                          | (f, result) <- results
-                          ] :: [Either (FilePath, Text) (FilePath, ByteString)]
-            in
-                case partitionEithers eithers of
-                    (errors@(_ : _), _) ->
-                        Left $ CompileError $ M.fromList errors
-                    ([], outs) -> Right $ M.fromList outs
+            buildPackage pkg