wip test

.github/workflows/generate-docs.yml

@@ -29,7 +29,12 @@ jobs:
 
       - name: Set output
         id: set-output
-        run: echo "readme=$(cat README.md | base64)" >> $GITHUB_OUTPUT
+        run: |
+          {
+            echo 'readme<<EOF'
+            cat README.md
+            echo EOF
+          } >> "$GITHUB_OUTPUT"
 
   commit_docs:
     name: Commit action documentation
@@ -56,7 +61,7 @@ jobs:
         run: yarn install --frozen-lockfile
 
       - name: Get README from output
-        run: echo "${{ needs.generate_docs.outputs.readme }}" | base64 -d > README.md
+        run: echo "${{ needs.generate_docs.outputs.readme }}" > README.md
 
       - name: Format README
         run: yarn prettier -w --single-quote README.md

gh-actions-docs/README.md

@@ -2,7 +2,19 @@
 
 Automatically generate documentation for your GitHub Actions.
 
-## Setup
+## Usage
+
+The documentation will be added to the file `README.md` in the current directory.
+To specify where the documentation should be added, add the following two comments to the file:
+
+```markdown
+<!--gh-actions-docs path=your/cool/action.yml owner=3lvia project=cool-action version=v3 -->
+<!--gh-actions-docs-end -->
+```
+
+The `path` parameter is required, and the `owner`, `project`, and `version` parameters are optional.
+The latter three are only used to generate the "Usage" section of the documentation.
+If any of these are omitted, the "Usage" section will not be generated.
 
 ### Docker
 
@@ -21,37 +33,63 @@ cabal install
 gh-actions-docs
 ```
 
-## Usage
-
-The documentation will be added to the file `README.md` in the current directory.
-To specify where the documentation should be added, add the following two comments to the file:
-
-```markdown
-<!--gh-actions-docs path=your/cool/action.yml owner=3lvia project=cool-action version=v3 -->
-<!--gh-actions-docs-end -->
-```
-
-The `path` parameter is required, and the `owner`, `project`, and `version` parameters are optional.
-The latter three are only used to generate the "Usage" section of the documentation.
-If any of these are omitted, the "Usage" section will not be generated.
-
 ### GitHub Actions
 
 ```yaml
-name: Generate documentation
+name: Generate action documentation
 
 on:
   push:
     branches: [trunk]
 
 jobs:
   generate_docs:
-    name: Generate documentation
+    name: Generate action documentation
     runs-on: ubuntu-latest
+    outputs:
+      readme: ${{ steps.set-output.outputs.readme }}
+    container:
+      image: ghcr.io/3lvia/core-github-actions-templates/gh-actions-docs:latest
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
       - name: Generate action documentation
-        uses: 3lvia/core-github-actions-templates/gh-actions-docs@trunk
+        run: gh-actions-docs
+        env:
+          IGNORE_FILES: 'my-new-action/action.yml'
+          IGNORE-HEADERS: '# core-github-actions-templates,## Table of Contents'
+
+      - name: Set output
+        id: set-output
+        run: |
+          {
+            echo 'readme<<EOF'
+            cat README.md
+            echo EOF
+          } >> "$GITHUB_OUTPUT"
+
+
+  output_docs:
+    name: Output action documentation
+    runs-on: ubuntu-latest
+    needs: [generate_docs]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Get README from output
+        run: echo "${{ needs.generate_docs.outputs.readme }}" > README.md
 ```
+
+#### Environment variables
+
+- `README_FILE`: The file to write the documentation to. Defaults to `README.md`.
+- `DEBUG`: Set to `true` to enable debug output.
+- `IGNORE_FILES`: Comma-separated list of YAML files to ignore.
+- `IGNORE_HEADERS`: Comma-separated list of headers to ignore.
+- `NO_ACTIONS`: Set to `true` to disable generation of actions documentation.
+- `NO_TOC`: Set to `true` to disable generation of table of contents.

gh-actions-docs/app/Main.hs

@@ -32,6 +32,8 @@ data Config
     , debug         :: Bool
     , ignoreHeaders :: [String]
     , ignoreFiles   :: [String]
+    , noActions     :: Bool
+    , noToc         :: Bool
     }
     deriving (Show)
 
@@ -42,7 +44,12 @@ getConfig = do
     let debug' = lookup "DEBUG" env == Just "true"
     let ignoreHeaders' = maybe [] (splitOn "," . pack) $ lookup "IGNORE_HEADERS" env
     let ignoreFiles' = maybe [] (splitOn "," . pack) $ lookup "IGNORE_FILES" env
-    return $ Config readmeFile' debug' (map unpack ignoreHeaders') (map unpack ignoreFiles')
+    let noActions' = lookup "NO_ACTIONS" env == Just "true"
+    let noToc' = lookup "NO_TOC" env == Just "true"
+    when (noToc' && noActions') do
+        putStrLn "Both NO_TOC and NO_ACTIONS are set to true, nothing to do."
+        exitFailure
+    return $ Config readmeFile' debug' (map unpack ignoreHeaders') (map unpack ignoreFiles') noActions' noToc'
 
 -- ACTIONS
 
@@ -260,16 +267,9 @@ tableOfContentsTagParser = do
 
 -- MAIN
 
-main :: IO ()
-main = do
-    config <- getConfig
-    when (debug config) do
-        putStrLn "\nDebug mode enabled\n"
-        putStrLn "Config:"
-        pPrint config
-
-    readme <- readFile $ readmeFile config
 
+updateActions :: Config -> String -> IO String
+updateActions config readme = do
     -- Parse action metadata
     let actionMetadataListE = parse fromTextActionMetadataParser "" $ pack readme
     when (isLeft actionMetadataListE) do
@@ -303,17 +303,19 @@ main = do
     let readmeWithActions = foldl replaceActionTagWithDocs readme parsedFilesWithMetadata
     if readmeWithActions /= readme
         then do
-            writeFile "README.md" readmeWithActions
-            putStrLn $ readmeFile config ++ " updated successfully! (actions)"
+            putStrLn $ readmeFile config ++ " updated successfully with documentation for actions!"
         else do
-            putStrLn "Actions not updated."
+            putStrLn "No new changes, action documentation not updated."
+
+    return readmeWithActions
 
-    -- Parse markdown headers
+updateToc :: Config -> String -> IO String
+updateToc config readme = do
     let markdownHeaderLines =
             map (++ "\n") $
                 filter (`notElem` ignoreHeaders config) $
                     filter (\x -> any (`isPrefixOf` pack x) ["# ", "## ", "### ", "#### "]) $
-                        lines readmeWithActions
+                        lines readme
     when (debug config) do
         putStrLn "markdownHeadersLines:"
         pPrint markdownHeaderLines
@@ -334,10 +336,32 @@ main = do
         pPrint toc
 
     -- Update README with table of contents
-    let readmeWithActionsToc = replaceTableOfContentsTagWithTableOfContents toc readmeWithActions
-    if readmeWithActionsToc /= readmeWithActions
+    let readmeWithToc = replaceTableOfContentsTagWithTableOfContents toc readme
+    if readmeWithToc /= readme
         then do
-            writeFile "README.md" readmeWithActionsToc
-            putStrLn $ readmeFile config ++ " updated successfully! (toc)"
+            putStrLn $ readmeFile config ++ " updated successfully with table of contents!"
         else do
-            putStrLn "Table of contents not updated."
+            putStrLn "No new changes, table of contents not updated."
+
+    return readmeWithToc
+
+main :: IO ()
+main = do
+    config <- getConfig
+    when (debug config) do
+        putStrLn "\nDebug mode enabled\n"
+        putStrLn "Config:"
+        pPrint config
+
+    readme <- readFile $ readmeFile config
+
+    case (noActions config, noToc config) of
+        (False, False) ->
+            updateActions config readme >>= updateToc config >>= writeFile (readmeFile config)
+        (False, True) ->
+            updateActions config readme >>= writeFile (readmeFile config)
+        (True, False) ->
+            updateToc config readme >>= writeFile (readmeFile config)
+        (True, True) -> do
+            putStrLn "Both NO_TOC and NO_ACTIONS are set to true, nothing to do."
+            exitFailure