[ 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: 2 people

travis/agda-logo.svg .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 .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 .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."
   ]
 
 

travis/landing-bottom.html .github/tooling/landing-bottom.html

@@ -0,0 +1 @@
+*

travis/landing-top.html .github/tooling/landing-top.html

@@ -0,0 +1,4 @@
+name: standard-library-dev
+include: . ../src
+flags:
+  --warning=noUnsupportedIndexedMatch

travis/landing.sh .github/tooling/landing.sh

@@ -61,20 +61,12 @@ procedure should be followed:
 * Announce the release of the new version on the Agda mailing lists
   (users and developers).
 
-* Add v$VERSION to the list of protected directories in the .travis.yml
-  file of BOTH master and experimental. They should look something like:
-
-  >  git checkout HEAD -- v0.16/ v0.17/ v1.0/ v1.1/ (...)
-
-  Commit & push these changes. This will prevent the next step from being
-  overwritten by travis.
-
 * Generate and upload documentation for the released version:
 
-    cp travis/* .
+    cp .github/tooling/* .
     runhaskell GenerateEverything.hs
     ./index.sh
-    agda -i. -isrc --html index.agda
+    agda -i. -idoc -isrc --html index.agda
     mv html v$VERSION
     git checkout gh-pages
     git add v$VERSION/*.html v$VERSION/*.css

.github/workflows/ci-ubuntu.yml

@@ -0,0 +1,4 @@
+name: standard-library-doc
+include: . ../src
+flags:
+  --warning=noUnsupportedIndexedMatch

CHANGELOG.md

@@ -5,7 +5,6 @@ included-dirs:
 included-files:
   - "*.agda"
   - "*.md"
-  - ".travis.yml"
 
 excluded-files:
   - "README/Text/Tabular.agda"