Add a README to the files generated by cabal init

See #11231

Author: Kleidukos

cabal-install/src/Distribution/Client/Init/Defaults.hs

@@ -23,6 +23,7 @@ module Distribution.Client.Init.Defaults
   , defaultLicenseIds
   , defaultMainIs
   , defaultChangelog
+  , defaultReadme
   , defaultCategories
   , defaultInitFlags
   , defaultLanguage
@@ -75,6 +76,9 @@ defaultPackageType = Executable
 defaultChangelog :: FilePath
 defaultChangelog = "CHANGELOG.md"
 
+defaultReadme :: FilePath
+defaultReadme = "README.md"
+
 defaultLicense :: CabalSpecVersion -> SpecLicense
 defaultLicense csv
   | csv < CabalSpecV2_2 = SpecLicense $ Right AllRightsReserved

cabal-install/src/Distribution/Client/Init/FileCreators.hs

@@ -18,6 +18,7 @@ module Distribution.Client.Init.FileCreators
   ( -- * Commands
     writeProject
   , writeLicense
+  , writeReadme
   , writeChangeLog
   , prepareLibTarget
   , prepareExeTarget
@@ -70,6 +71,7 @@ writeProject (ProjectSettings opts pkgDesc libTarget exeTarget testTarget)
 
       writeLicense opts pkgDesc
       writeChangeLog opts pkgDesc
+      writeReadme opts pkgDesc
 
       let pkgFields = mkPkgDescription opts pkgDesc
           commonStanza = mkCommonStanza opts
@@ -240,6 +242,28 @@ writeChangeLog opts pkgDesc
     go =
       void $ writeFileSafe opts defaultChangelog changeLog
 
+writeReadme :: Interactive m => WriteOpts -> PkgDescription -> m ()
+writeReadme opts pkgDesc
+  | Just docs <- _pkgExtraDocFiles pkgDesc
+  , defaultReadme `Set.member` docs =
+      go
+  | defaultReadme `elem` _pkgExtraSrcFiles pkgDesc = go
+  | otherwise = return ()
+  where
+    readme =
+      unlines
+        [ "# " ++ prettyShow (_pkgName pkgDesc)
+        , ""
+        , "## Build"
+        , ""
+        , "Run `$ cabal build` to build the project"
+        , "## Documentation"
+        , ""
+        , "Run `$ cabal haddock --open` to generate a reference for the API of the project."
+        ]
+    go =
+      void $ writeFileSafe opts defaultReadme readme
+
 -- -------------------------------------------------------------------- --
 -- Utilities
 

cabal-install/src/Distribution/Client/Init/FlagExtractors.hs

@@ -138,7 +138,7 @@ getExtraDocFiles :: Interactive m => InitFlags -> m (Maybe (Set String))
 getExtraDocFiles =
   pure
     . Just
-    . flagElim (Set.singleton defaultChangelog) Set.fromList
+    . flagElim (Set.fromList [defaultChangelog, defaultReadme]) Set.fromList
     . extraDoc
 
 -- | Ask whether the project builds a library or executable.

cabal-install/src/Distribution/Client/Init/NonInteractive/Heuristics.hs

@@ -101,7 +101,7 @@ guessExtraDocFiles flags = do
   return $
     Just $
       if null extraDocs
-        then Set.singleton defaultChangelog
+        then Set.fromList [defaultChangelog, defaultReadme]
         else Set.fromList extraDocs
 
 -- | Try to guess the package type from the files in the package directory,

cabal-install/src/Distribution/Client/Init/Simple.hs

@@ -112,7 +112,7 @@ createProject v pkgIx _srcDb initFlags = do
 genSimplePkgDesc :: Interactive m => InitFlags -> m PkgDescription
 genSimplePkgDesc flags = mkPkgDesc <$> currentDirPkgName
   where
-    defaultExtraDoc = Just $ Set.singleton defaultChangelog
+    defaultExtraDoc = Just $ Set.fromList [defaultChangelog, defaultReadme]
 
     extractExtraDoc [] = defaultExtraDoc
     extractExtraDoc fs = Just $ Set.fromList fs

cabal-install/tests/UnitTests/Distribution/Client/Init/Interactive.hs

@@ -627,7 +627,7 @@ createProjectTest pkgIx srcDb =
                 flags =
                   emptyFlags
                     { cabalVersion = Flag CabalSpecV1_10
-                    , extraDoc = Flag [defaultChangelog]
+                    , extraDoc = Flag [defaultChangelog, defaultReadme]
                     , extraSrc = Flag ["README.md"]
                     }
 
@@ -650,7 +650,7 @@ createProjectTest pkgIx srcDb =
                 _pkgHomePage desc @?= "qux.com"
                 _pkgSynopsis desc @?= "Qux's package"
                 _pkgCategory desc @?= "Control"
-                _pkgExtraSrcFiles desc @?= Set.fromList [defaultChangelog, "README.md"]
+                _pkgExtraSrcFiles desc @?= Set.fromList [defaultChangelog, defaultReadme]
                 _pkgExtraDocFiles desc @?= Nothing
 
                 _libSourceDirs lib @?= ["src"]

cabal-install/tests/UnitTests/Distribution/Client/Init/Simple.hs

@@ -168,7 +168,7 @@ simplePkgDesc pkgName =
     ""
     ""
     mempty
-    (Just $ Set.singleton defaultChangelog)
+    (Just $ Set.fromList [defaultReadme, defaultChangelog])
 
 simpleLibTarget :: [Dependency] -> LibTarget
 simpleLibTarget baseDep =