targets.docs.title config to render <title>

CHANGES.md

@@ -111,6 +111,12 @@ To be released.
     union qux = bar (text a) | quux (text b);
     ~~~~~~~~
 
+### Docs target
+
+ -  A new required configuration `targets.docs.title` was added.
+    It's rendered in generated HTML documents' `<title>` element.
+    [[#253]]
+
 ### Python target
 
  -  Generated Python packages became to have two [entry points] (a feature
@@ -159,8 +165,10 @@ To be released.
 [#13]: https://github.com/spoqa/nirum/issues/13
 [#220]: https://github.com/spoqa/nirum/issues/220
 [#227]: https://github.com/spoqa/nirum/pull/227
+[#253]: https://github.com/spoqa/nirum/pull/253
 [entry points]: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
 [python2-numbers-integral]: https://docs.python.org/2/library/numbers.html#numbers.Integral
+[python2-int]: https://docs.python.org/2/library/functions.html#int
 [python2-basestring]: https://docs.python.org/2/library/functions.html#basestring
 [python2-unicode]: https://docs.python.org/2/library/functions.html#unicode
 [glibc]: https://www.gnu.org/software/libc/

docs/annotation.md

@@ -76,7 +76,7 @@ The following annotations are common among more than one target languages.
 For target-specific annotations, read each target's docs.
 
 
-### `@docs` (`docs`)
+### `@docs` (`docs`)                                                     {#docs}
 
 `@docs` annotations represent docs comments (`# ...`).  The following two
 examples are equivalent, and the former is internally transformed to the latter:
@@ -102,7 +102,7 @@ a time.
 :   A docs text.
 
 
-### `@error`
+### `@error`                                                            {#error}
 
 Many object-oriented languages (e.g., Java, Python) require exception classes
 to inherit a specific base class (e.g., `Exception`) to be thrown.

docs/target/docs.md

@@ -0,0 +1,34 @@
+Docs target
+===========
+
+This target does not generate any program code files, but HTML pages (and
+some extra assets like CSS).  It generates a kind of API reference docs for
+the given Nirum package: type definitions, union tags, enum members,
+service methods, and so on.
+
+
+Docs comments
+-------------
+
+Nirum provide two kinds of comments.  One is an ordinary comment which starts
+with `//`, and other one is a docs comment which begins with `#`.  Docs target
+is only aware of the latter.
+
+Docs comments are, unlike ordinal comments, not allowed to any places, but only
+allowed to some specific places.
+
+Docs comments are actually a syntactic sugar of [`@docs`](../annotation.md#docs)
+annotation, hence allowed to be attached to only where annotations are allowed:
+declarations that have a name, e.g., types, fields, members, services, methods,
+parameters, modules.
+
+You can find *examples/shapes.nrm* to see examples of docs comments.
+
+
+Settings
+--------
+
+### `title` (required): Docs title
+
+It goes to `<title>` elements of generated HTML pages.  It's usually a name of
+the Nirum package.

examples/package.toml

@@ -3,3 +3,6 @@ version = "0.3.0"
 [targets.python]
 name = "nirum-examples"
 minimum_runtime = "0.3.9"
+
+[targets.docs]
+title = "Nirum Examples"

package.yaml

@@ -137,6 +137,7 @@ tests:
     - hspec
     - hspec-core
     - hspec-meta
+    - hxt >=9.3.1.16 && <9.4.0.0
     - nirum
     - process >=1.1 && <2
     - semigroups

src/Nirum/Targets/Docs.hs

@@ -52,12 +52,15 @@ import Nirum.Package.Metadata ( Author (Author, email, name, uri)
                                        , targetName
                                        , toByteString
                                        )
+                              , stringField
                               )
 import qualified Nirum.Package.ModuleSet as MS
 import Nirum.TypeInstance.BoundModule
 import Nirum.Version (versionText)
 
-data Docs = Docs deriving (Eq, Ord, Show)
+newtype Docs = Docs
+    { docsTitle :: T.Text
+    } deriving (Eq, Ord, Show)
 
 type Error = T.Text
 
@@ -104,8 +107,8 @@ $case expr'
 |]
 
 module' :: BoundModule Docs -> Html
-module' docsModule = layout pkg depth path $ [shamlet|
-    $maybe tit <- title
+module' docsModule = layout pkg depth title $ [shamlet|
+    $maybe tit <- headingTitle
         <h1><code>#{path}</code>
         <p>#{tit}
     $nothing
@@ -121,6 +124,8 @@ module' docsModule = layout pkg depth path $ [shamlet|
     pkg = boundPackage docsModule
     path :: T.Text
     path = toCode docsModulePath
+    title :: T.Text
+    title = T.concat [path, " \8212 ", docsTitle $ target pkg]
     types' :: [(Identifier, TD.TypeDeclaration)]
     types' = [ (facialName $ DE.name decl, decl)
              | decl <- DES.toList $ boundTypes docsModule
@@ -130,8 +135,8 @@ module' docsModule = layout pkg depth path $ [shamlet|
              ]
     mod' :: Maybe Module
     mod' = resolveModule docsModulePath pkg
-    title :: Maybe Html
-    title = do
+    headingTitle :: Maybe Html
+    headingTitle = do
         m <- mod'
         moduleTitle m
     depth :: Int
@@ -258,7 +263,7 @@ showKind TD.Import {} = "import"
 contents :: Package Docs -> Html
 contents pkg@Package { metadata = md
                      , modules = ms
-                     } = layout pkg 0 ("Package docs" :: T.Text) [shamlet|
+                     } = layout pkg 0 title [shamlet|
 <h1>Modules
 $forall (modulePath', mod) <- MS.toAscList ms
     $maybe tit <- moduleTitle mod
@@ -285,6 +290,8 @@ $forall (modulePath', mod) <- MS.toAscList ms
                 <dd.author>#{n}
 |]
   where
+    title :: T.Text
+    title = docsTitle $ target pkg
     emailText :: E.EmailAddress -> T.Text
     emailText = decodeUtf8 . E.toByteString
 
@@ -372,7 +379,9 @@ instance Target Docs where
     type CompileResult Docs = BS.ByteString
     type CompileError Docs = Error
     targetName _ = "docs"
-    parseTarget _ = return Docs
+    parseTarget table = do
+        title <- stringField "title" table
+        return Docs { docsTitle = title }
     compilePackage = compilePackage'
     showCompileError _ = id
     toByteString _ = id

test/Nirum/Targets/DocsSpec.hs

@@ -1,16 +1,25 @@
 {-# LANGUAGE OverloadedLists #-}
 module Nirum.Targets.DocsSpec where
 
+import Control.Monad
+import GHC.Exts (IsList (toList))
+
+import Data.Text hiding (empty)
+import Data.Text.Encoding
 import System.FilePath ((</>))
 import Test.Hspec.Meta
 import Text.Blaze.Html.Renderer.Utf8 (renderHtml)
+import Text.XML.HXT.Core hiding (when)
 
 import Nirum.Constructs.Annotation (empty)
 import Nirum.Constructs.DeclarationSet (DeclarationSet)
 import Nirum.Constructs.Module (Module (..))
 import Nirum.Constructs.TypeDeclaration (TypeDeclaration (Import))
 import qualified Nirum.Docs as D
+import Nirum.Package
+import Nirum.Package.Metadata (Target (compilePackage, toByteString))
 import qualified Nirum.Targets.Docs as DT
+import Nirum.TestFixtures
 
 spec :: Spec
 spec = describe "Docs" $ do
@@ -31,3 +40,17 @@ spec = describe "Docs" $ do
     specify "blockToHtml" $ do
         let h = D.Paragraph [D.Strong ["Hi!"]]
         renderHtml (DT.blockToHtml h) `shouldBe` "<p><strong>Hi!</strong></p>"
+    specify "<title>" $ do
+        pkg <- fixturePackage
+        let t = target pkg
+        forM_ (toList $ compilePackage (pkg :: Package DT.Docs)) $ \ (f, r) ->
+            when (".html" `isSuffixOf` pack f) $ do
+                let Right html = r
+                let doc = readString
+                              [withParseHTML yes, withWarnings no]
+                              (unpack . decodeUtf8 . toByteString t $ html)
+                titles <- runX $ doc //> hasName "title" /> getText
+                titles `shouldNotBe` []
+                forM_ titles $ \ title ->
+                    pack title `shouldSatisfy`
+                        isSuffixOf "Fixtures for Nirum tests"

test/Nirum/TestFixtures.hs

@@ -0,0 +1,22 @@
+module Nirum.TestFixtures (fixturePackage, scanFixturePackage) where
+
+import Control.Monad
+import Data.Either
+
+import System.FilePath
+
+import Nirum.Package
+import Nirum.Package.Metadata
+
+
+-- | Scan test/nirum_fixture/ package.
+scanFixturePackage :: Target t => IO (Either PackageError (Package t))
+scanFixturePackage = scanPackage $ "test" </> "nirum_fixture"
+
+-- | Unsafe version of 'scanFixturePackage'.
+fixturePackage :: Target t => IO (Package t)
+fixturePackage = do
+    result <- scanFixturePackage
+    when (isLeft result) $ fail ("result: " ++ show result)
+    let Right pkg = result
+    return pkg

test/nirum_fixture/package.toml

@@ -7,8 +7,10 @@ keywords = ["sample", "example", "nirum"]
 name = "nirum"
 email = "[email protected]"
 
-[targets]
 [targets.python]
 name = "nirum_fixture"
 [targets.python.renames]
 "renames.test" = "renamed"
+
+[targets.docs]
+title = "Fixtures for Nirum tests"