PR - Webpage Updating (Intro, generated code headings, Documentation, icon)

code/scripts/deploy_stage.sh

@@ -71,11 +71,17 @@ copy_examples() {
 		if [ -d "$example/"src ]; then
 			# We don't expose code in deploy. It's more conveneient to link to GitHub's directory
 			# We place a stub file which Hakyll will replace.
-			echo $(cd "$CUR_DIR" && "$MAKE" deploy_code_path | grep "$example_name" | cut -d"$DEPLOY_CODE_PATH_KV_SEP" -f 2-) > "$EXAMPLE_DEST$example_name/src"
+      REL_PATH=$(cd "$CUR_DIR" && "$MAKE" deploy_code_path | grep "$example_name" | cut -d"$DEPLOY_CODE_PATH_KV_SEP" -f 2-)
+      ls -d "$(git rev-parse --show-toplevel)/$REL_PATH"*/ | rev | cut -d/ -f2 | rev | tr '\n' '\0' | xargs -0 printf "$REL_PATH%s\n" > "$EXAMPLE_DEST$example_name/src"
 		fi
 	done
 }
 
+copy_images() {
+  mkdir -p "$CUR_DIR"deploy/images
+  cp -r "$CUR_DIR"website/images/ "$CUR_DIR"deploy/images
+}
+
 build_website() {
 	cd "$CUR_DIR"website
 	make DEPLOY_FOLDER="$CUR_DIR$DEPLOY_FOLDER" DOCS_FOLDER="$DOC_DEST" EXAMPLES_FOLDER="$EXAMPLE_DEST" \
@@ -98,5 +104,6 @@ copy_docs
 copy_graphs
 copy_datafiles
 copy_examples
+copy_images
 build_website
 cd "$CUR_DIR"

code/website/css/styles.css

@@ -1,6 +1,6 @@
 body {
   /* background-color: rgb(236, 236, 236); */
-  background-image: linear-gradient(to bottom, rgba(0, 0, 0, 0), rgba(0, 0, 0, 0.05));
+  /* background-image: linear-gradient(to bottom, rgba(0, 0, 0, 0), rgba(0, 0, 0, 0.05)); */
   font-family: Roboto;
   padding-left: 3%;
   padding-right: 3%;

code/website/index.html

@@ -3,11 +3,19 @@ <h2>Drasil - Generate All the Things!</h2>
 <hr>
 <br>
 <p>
+  Drasil is a framework for generating all of the software artifacts from a stable knowledge base,
+  focusing currently on scientific software. The main goals are to reduce knowledge duplication and
+  improve traceability. The atifacts are generated from a common knowledge-base using recipes
+  written in a Domain-Specific Language (DSL). These recipes allow us to specify which pieces of
+  knowledge should be used in which artifacts, how to transform them, and more.
+  <br><br>
   This webpage is designed to contain the most up to date
-  <a href="#caseStudies">case study artifacts</a>
+  <a href="#caseStudies">case study artifacts</a>,
+  $if(docsUrl)$ <a href="#haskDoc">Haddock documentation</a>, $endif$
   and <a href="#packages">package dependency graphs</a> from the Drasil repository.
   The case study artifacts include the Software Requirements Specification (SRS) for the case study,
   which specifies what the program sets out to achieve.
+  The Haddock Documentation section contains the current documentation for the Drasil framework.
   The package dependency graphs shows the hierarchy of modules within each package.
   The footer of this page contains the continuous integration build of the project,
   as well as the commit number that the build and artifacts are based off of.
@@ -27,17 +35,27 @@ <h3 id="caseStudies">Case Studies</h3>
           <a href="$url$">[$type$]</a>
         $-endfor$
       </li>
-    $-if(src)$
-      <li><a href="$src-$">Generated Code</a></li>
-    $-endif$
+      $-if(src)$
+        <li>
+          Generated Code:
+          $-for(src)$
+            <a href="$path$">[$lang$]</a>
+          $-endfor$
+        </li>
+      $-endif$
     </ul>
     <br>
   </li>$sep-$
 $endfor$
 </ul>
+
 $if(docsUrl)-$
-<h4><a href="$docsUrl$">Haskell Documentation</a></h4>
+  <h3 id="haskDoc">Haddock Documentation</h3>
+  <p>
+    The current <a href="$docsUrl$">Haddock documentation</a> for the Drasil framework.
+  </p>
 $-endif$
+
 <h3 id="packages">Package Dependency Graphs</h3>
 <ul>
   $-for(graphs)$

code/website/site.hs

@@ -13,10 +13,10 @@ import System.FilePath (takeBaseName, takeExtension)
 
 -- type FilePath = String -- from System.FilePath
 type Name = String
-type SourceLocation = Maybe String
+type CodeSource = (FilePath, String)
 type SRSVariants = [(Name, String)]
 type Description = Maybe String
-data Example = E Name SourceLocation SRSVariants Description
+data Example = E Name [CodeSource] SRSVariants Description
 
 -- Returns FilePath of the SRS
 srsPath :: FilePath -> FilePath -> FilePath -> FilePath
@@ -33,46 +33,102 @@ getExtensionName _ = error "Expected some extension."
 getSRS :: [Name] -> SRSVariants
 getSRS = map (\x -> (x, getExtensionName $ takeExtension x)) . filter (\x -> any (`endswith` x) [".pdf", ".html"])
 
+-- returns a tuple of the link to the specific code folder and its language in the form (urlPath, Language)
+getSrc :: String -> FilePath -> CodeSource
+-- source comes in as a path, takeBaseName takes only rightmost folder name
+getSrc repoRoot source = (repoRoot ++ source, lang $ takeBaseName source)
+  where
+    -- Some languages might be named differently than the folders they are stored in.
+    lang "cpp"    = "C++"
+    lang "csharp" = "C#"
+    lang "python" = "Python"
+    lang "java"   = "Java"
+    lang x        = error ("No given display name for language: " ++ x)
+
 mkExamples :: String -> FilePath -> FilePath -> IO [Example]
 mkExamples repoRoot path srsDir = do
-  -- names will be a list of example names (Chipmunk, GlassBR, etc. of type FilePath)
+
+  -- names will be a sorted list of example names (Chipmunk, GlassBR, etc.) of type FilePath
   names <- sort <$> (listDirectory path >>= filterM (\x -> doesDirectoryExist $ path ++ x))
 
-  -- a list of Just sources or Nothing based on existence and contents of src file.
+  -- a list of lists of sources based on existence and contents of src file for each example.
+  -- if no src file, then the inner list will be empty
   sources <- mapM (\x -> doesFileExist (path ++ x ++ "/src") >>=
-      \y -> if y then Just . (++) repoRoot . rstrip <$> readFile (path ++ x ++ "/src") else return Nothing) names
+    \y -> if y then map (getSrc repoRoot) . lines . rstrip <$> readFile (path ++ x ++ "/src") else return []) names
+
 
   -- a list of Just descriptions or Nothing based on existence and contents of desc file.
   descriptions <- mapM (\x -> doesFileExist ("descriptions/" ++ x ++ ".txt") >>=
-      \y -> if y then Just . rstrip <$> readFile ("descriptions/" ++ x ++ ".txt") else return Nothing) names
+    \y -> if y then Just . rstrip <$> readFile ("descriptions/" ++ x ++ ".txt") else return Nothing) names
 
   -- creates a list of SRSVariants, so a list of list of tuples.
   -- the outer list has an element for each example.
   srss <- mapM (\x -> sort . getSRS <$> listDirectory (srsPath path x srsDir)) names
 
   -- returns the IO list of examples with constructor E containing
-  -- the name of the example, sources (if applicable), and the list of Variants.
+  -- the name of the example, sources, list of variants, and description
   return $ map (\(name, source, srs, desc) -> E name source srs desc) $ zip4 names sources srss descriptions
 
 maybeField :: String -> (Item a -> Compiler (Maybe String)) -> Context a
 maybeField s f = Context $ \k _ i -> do
+  -- val will be of type Maybe String
   val <- f i
+  -- if val is Just and the input string matches the html file paramater,
+  -- then we use the String contained in val
   if k == s && isJust val then
     return $ StringField $ fromJust val
   else
+    -- Otherwise, fail acts to not use the $if$ parameter in the html file
     fail $ "maybeField " ++ s ++ " used when really Nothing. Wrap in `$if(" ++ s ++ ")$` block."
 
+-- List if non-empty
+maybeListFieldWith :: String -> Context a -> (Item b -> [c]) -> (Item b -> Compiler [Item a]) -> Context b
+-- takes as input: the string to be replaced, the context to be used as is,
+-- a function to be used on input to return a list to check for emptiness,
+-- and the function to be used regularly on input
+maybeListFieldWith s contxt checkNull f = listFieldWith s contxt
+  -- If the list is empty, fail is used so as not to create a specific section
+  (\x -> if null (checkNull x) then fail ("No instances of " ++ s) else f x)
+
 mkExampleCtx :: FilePath -> FilePath -> Context Example
 mkExampleCtx exampleDir srsDir =
+  -- each function is applied to the item containing an Example of form:
+  -- E Name [CodeSource] SRSVariants Description
+
+  -- here, listFieldWith used with multiple versions of SRS per example
   listFieldWith "srs" (
+    -- field will replace the string parameters in the html with the returned string
+    -- <> acts as a semigroup concatenator
+
+    -- returns filename from ((filename, TYPE), E _ _ _ _)
     field "filename" (return . fst . srsVar) <>
+    -- returns TYPE from ((_, _), E _ _ _ _)
     field "type" (return . snd . srsVar) <>
+    -- returns name from ((_, _), E name [codeSource] srsVariants description)
+    -- which is the same name as the outer scope example name
     field "name" (return . name . example) <>
+    -- gets the URL by taking the path to the srs ++ the filename of the srs
     field "url" (\x -> return $ srsPath exampleDir (name $ example x) srsDir ++ fst (srsVar x))
+  -- creates a list of items where each item contains a tuple
+  -- the tuple contains (specific srs variant, general Example)
+  -- in this way, each srs variant is accounted for, and all information can be accessible 
   ) (\x -> mapM (\y -> makeItem (y, itemBody x)) $ srs $ itemBody x)  <>
+
+  -- Fills in the overall name of each example
+  -- by returning name from E name [codeSource] srsVariants description
   field "name" (return . name . itemBody) <>
+  -- returns the description of an example if Just, otherwise fails and does not add one
   maybeField "desc" (return . desc . itemBody) <>
-  maybeField "src" (return . src . itemBody)
+
+  -- Lists sources if they exist
+  maybeListFieldWith "src" (
+    -- return filepath from (filepath, language)
+    field "path" (return . fst . itemBody) <>
+    -- return language from (filepath, language)
+    field "lang" (return . snd . itemBody)
+  -- (src . itemBody) gets the list of sources to be checked for emptiness
+  -- (mapM makeItem . src . itemBody) rewraps every item in src to be used internally
+  ) (src . itemBody) (mapM makeItem . src . itemBody)
   where
     name (E nm _ _ _) = nm
     src (E _ s _ _) = s
@@ -82,11 +138,14 @@ mkExampleCtx exampleDir srsDir =
     example = snd . itemBody
 
 mkGraphs :: FilePath -> IO [FilePath]
+-- returns an IO list of the paths to all graphs based on an input path
 mkGraphs path = sort . filter (endswith ".pdf") <$> listDirectory path
 
 mkGraphCtx :: FilePath -> Context FilePath
 mkGraphCtx graphRoot =
+  -- fills name with the base name of the file (ie. no paths or extensions)
   field "name" (return . takeBaseName . itemBody) <>
+  -- fills url with the link to the file based on the link to the root directory concatenated with the filename
   field "url" (return . (++) graphRoot . itemBody)
 
 main :: IO ()

code/website/templates/base.html

@@ -4,6 +4,7 @@
     <meta charset="utf-8">
     <title>Drasil</title>
     <link rel="stylesheet" type="text/css" href="css/styles.css">
+    <link rel="icon" href="images/Icon.png" sizes="32x32">
   </head>
   <body>
     $body-$