[ fix #1743 ] move README to doc/ directory (#2184)

* [ admin ] dev playground

* [ fix #1743 ] move README to doc/ directory

* [ fix ] whitespace violations

* [ ci ] update to cope with new doc/ directory

* [ cleanup ] remove stale reference to travis.yml

* [ admin ] update README-related instructions

* [ admin ] fix build badges

* [ fix ] `make test` build

* Moved contents of notes/ to doc/

* Added CHANGELOG entry

---------

Co-authored-by: MatthewDaggitt <[email protected]>

Author: gallais

travis/agda-logo.svg renamed to .github/tooling/agda-logo.svg

@@ -51,7 +51,7 @@ env:
   CABAL_VERSION: 3.6.2.0
   CABAL_INSTALL: cabal v1-install --ghc-options='-O1 +RTS -M6G -RTS'
   # CABAL_INSTALL: cabal install --overwrite-policy=always --ghc-options='-O1 +RTS -M6G -RTS'
-  AGDA: agda -Werror +RTS -M3.5G -H3.5G -A128M -RTS -i. -i src/
+  AGDA: agda -Werror +RTS -M3.5G -H3.5G -A128M -RTS -i. -isrc -idoc
 
 jobs:
   test-stdlib:
@@ -152,7 +152,7 @@ jobs:
       - name: Test stdlib
         run: |
           cabal run GenerateEverything
-          cp travis/* .
+          cp .github/tooling/* .
           ./index.sh
           ${{ env.AGDA }} --safe EverythingSafe.agda
           ${{ env.AGDA }} index.agda
@@ -178,7 +178,7 @@ jobs:
           rm -f '${{ env.AGDA_HTML_DIR }}'/*.css
           ${{ env.AGDA }} --html --html-dir ${{ env.AGDA_HTML_DIR }} index.agda
 
-          cp travis/* .
+          cp .github/tooling/* .
           ./landing.sh
 
       - name: Deploy HTML

travis/index.agda renamed to .github/tooling/index.agda

@@ -9,23 +9,27 @@ AGDA=$(AGDA_EXEC) $(AGDA_OPTIONS) $(AGDA_RTS_OPTIONS)
 #   cabal install fix-whitespace
 
 test: Everything.agda check-whitespace
-	$(AGDA) -i. -isrc README.agda
+	cd doc && $(AGDA) README.agda
 
 testsuite:
 	$(MAKE) -C tests test AGDA="$(AGDA)" AGDA_EXEC="$(AGDA_EXEC)" only=$(only)
 
+fix-whitespace:
+	cabal exec -- fix-whitespace
+
 check-whitespace:
 	cabal exec -- fix-whitespace --check
 
 setup: Everything.agda
 
 .PHONY: Everything.agda
 Everything.agda:
-	cabal run GenerateEverything
+	cabal run GenerateEverything -- --out-dir doc
 
 .PHONY: listings
 listings: Everything.agda
-	$(AGDA) -i. -isrc --html README.agda -v0
+	cd doc && $(AGDA) --html README.agda -v0
 
 clean :
 	find . -type f -name '*.agdai' -delete
+	rm -f Everything.agda EverythingSafe.agda

travis/index.sh renamed to .github/tooling/index.sh

@@ -1,5 +1,6 @@
 {-# LANGUAGE PatternGuards #-}
 {-# LANGUAGE PatternSynonyms #-}
+{-# LANGUAGE RecordWildCards #-}
 
 import Control.Applicative
 import Control.Monad
@@ -299,18 +300,37 @@ checkFilePaths cat fps = forM_ fps $ \ fp -> do
   unless b $
     die $ fp ++ " is listed as " ++ cat ++ " but does not exist."
 
+data Options = Options
+  { includeDeprecated :: Bool
+  , outputDirectory :: FilePath
+  }
+
+initOptions :: Options
+initOptions = Options
+  { includeDeprecated = False
+  , outputDirectory = "."
+  }
+
+parseOptions :: [String] -> Options -> Maybe Options
+parseOptions [] opts = pure opts
+parseOptions ("--include-deprecated" : rest) opts
+  = parseOptions rest (opts { includeDeprecated = True })
+parseOptions ("--out-dir" : dir : rest) opts
+  = parseOptions rest (opts { outputDirectory = dir })
+parseOptions _ _ = Nothing
+
 ---------------------------------------------------------------------------
 -- Collecting all non-Core library files, analysing them and generating
--- 4 files:
+-- 2 files:
 -- Everything.agda                 all the modules
 -- EverythingSafe.agda             all the safe modules
 
+main :: IO ()
 main = do
   args <- getArgs
-  includeDeprecated <- case args of
-    [] -> return False
-    ["--include-deprecated"] -> return True
-    _  -> hPutStr stderr usage >> exitFailure
+  Options{..} <- case parseOptions args initOptions of
+    Just opts -> pure opts
+    Nothing -> hPutStr stderr usage >> exitFailure
 
   checkFilePaths "unsafe" unsafeModules
   checkFilePaths "using K" withKModules
@@ -325,14 +345,14 @@ main = do
 
   let mkModule str = "module " ++ str ++ " where"
 
-  writeFileUTF8 (allOutputFile ++ ".agda") $
+  writeFileUTF8 (outputDirectory ++ "/" ++ allOutputFile ++ ".agda") $
     unlines [ header
             , "{-# OPTIONS --rewriting --guardedness --sized-types #-}\n"
             , mkModule allOutputFile
             , format libraryfiles
             ]
 
-  writeFileUTF8 (safeOutputFile ++ ".agda") $
+  writeFileUTF8 (outputDirectory ++ "/" ++ safeOutputFile ++ ".agda") $
     unlines [ header
             , "{-# OPTIONS --safe --guardedness #-}\n"
             , mkModule safeOutputFile
@@ -353,6 +373,9 @@ usage = unlines
   , "The program generates documentation for the library by extracting"
   , "headers from library modules. The output is written to " ++ allOutputFile
   , "with the file " ++ headerFile ++ " inserted verbatim at the beginning."
+  , ""
+  , "If the option --out-dir is used then the output is placed in the"
+  , "subdirectory thus selected."
   ]