Github Action Consistently breaks

[ApplebaumIan]

So 1. Thank you @mattt for all of your help on Twitter! My documentation looks amazing now!
I'm not totally sure if my issue is related to #78 as we were discussing. It's very difficult for me to diagnose because it instantly fails

Ignore the fact that I'm using the Action from my fork because the error persists when I use swiftDocOrg/swift-doc@master

I'm wondering if there is anyway I could find a more comprehensive error log to see if this is in fact related to #78?

[ApplebaumIan]

My yaml in case you need it!

name: Document Code
on:
  # Trigger the workflow on push or pull request,
  # but only for the master branch
  push:
    branches:
      - master
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      - name: Generate Documentation
        uses: Applebaumian/swift-doc@master # I'm using my fork but the error happens on swiftDocOrg/swift-doc@master as well.
        with:
          inputs: "ImageClassification"
          module-name: iASL
          format: "html"
          output: "Documentation"
      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@releases/v3
        with:
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          BRANCH: gh-pages # The branch the action should deploy to.
          FOLDER: Documentation # The folder the action should deploy.
#       - name: Upload Documentation to Wiki
#         uses: SwiftDocOrg/github-wiki-publish-action@v1
#         with:
#           path: ".build/documentation"
#         env:
#           GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

[mattt]

Hey @ApplebaumIan, can you please provide a link to the failed action on GitHub (assuming it's public)?

To get more logging information, add a secret named ACTIONS_RUNNER_DEBUG with a value of true.

[ApplebaumIan]

Here you go! Also I'll try adding that debugger!
https://github.com/Capstone-Projects-2020-Spring/iASL-iOS/runs/594181504?check_suite_focus=true

[MattKiazyk]

I'm getting the same issue when generating html with github actions. Will fail with no errors. (unfortunately the repo is private but yaml is the same as above.

My guess is that if you add html documentation building in https://github.com/SwiftDocOrg/swift-doc/blob/master/.github/workflows/documentation.yml workflow you would possibly see the same thing.

Locally on Mac, html documentation builds with no errors

I'm wondering if perhaps this is because html tries to load the min.css external file and it can't? I'm not a docker pro so don't know if docker has permissions to load files externally?

[MattKiazyk]

@mattt latest master as of today, now successfully builds inside the action 💥 Guessing the #140 fixes the issue.

@ApplebaumIan might want to try latest master to see if this fixes it.

[ApplebaumIan]

@mattt latest master as of today, now successfully builds inside the action 💥 Guessing the #140 fixes the issue.

@ApplebaumIan might want to try latest master to see if this fixes it.

I'll make sure to give it a try thanks!

[stephencelis]

I've gotten things working but had to insert this step between the swift-doc action and the Github Pages action:

      - name: Update Permissions
        run: 'sudo chown --recursive $USER Documentation'

The output from the swift-doc action seems to have incorrect permissions.

[MattKiazyk]

I think that will hopefully be fixed in #146

I get the same permission issue.

[mattt]

#146 is now merged. @ApplebaumIan Please let me know if you're still seeing this issue.

[ApplebaumIan]

I'm sorry I'm taking so long to get back to you all! Last week of summer university physics course... I'll definitely check this out next week!

[ApplebaumIan]

So on the bright side Swift-Doc does not crash! 🥳

Not sure what the warnings are though. Also is there any documentation for how to publish the HTML documentation to gh-pages?

Something else to note is when I run swift-doc on my local machine I don't receive these GraphViz warnings!

[mattt]

@ApplebaumIan

Not sure what the warnings are though.

You're getting those warnings because you don't have GraphViz installed on your CI runner. You need to add a step that runs brew install graphviz.

Something else to note is when I run swift-doc on my local machine I don't receive these GraphViz warnings!

That's probably because installing swift-doc via Homebrew automatically installs GraphViz as a dependency. Same for the swift-doc GitHub Action, which comes with everything needed.

Because you're building from source with your own fork, you have to install GraphViz yourself.

Also is there any documentation for how to publish the HTML documentation to gh-pages?

You can use an action like this one to publish the generated content to your gh-pages branch.

[stephencelis]

@mattt As a heads-up it looks like I still need to run chown on the output to deploy it to GH pages.

[ApplebaumIan]

For whatever reason the swift-doc GitHub action keeps saying there are no public API Symbols in my project... now there isn't much public in our app but there definitely isn't zero.

Not sure what to make of it really... Also tried using the main swift-doc action instead of my fork and got the same results.

[mattt]

@ApplebaumIan Your workflow is missing a checkout step:

- name: Checkout
   uses: actions/checkout@v1

What it's doing right now is building swift-doc from source and running it in an otherwise empty directory.

[ApplebaumIan]

@ApplebaumIan Your workflow is missing a checkout step:

- name: Checkout
   uses: actions/checkout@v1

What it's doing right now is building swift-doc from source and running it in an otherwise empty directory.

Huh, it makes sense that it wouldn't work without the checkout step... however after adding the suggested checkout step I'm getting the same result... https://github.com/Capstone-Projects-2020-Spring/iASL-iOS/blob/master/.github/workflows/document.yml

Honestly I wouldn't be surprised if it was an issue with how I'm writing these actions... 😅

[mattt]

@ApplebaumIan The error message appears to be correct. Looking in the ImageClassification directory, there aren't any top-level symbols declared with a public access level.

[ApplebaumIan]

Yup turns out that it works with my fork and @stephencelis suggestion of using chown was required to deploy the pages! 🎉
Only hiccup is the stylesheet seems to be missing if you drill into a class! https://capstone-projects-2020-spring.github.io/iASL-iOS/

[mattt]

@ApplebaumIan Glad to hear that's working for you. The reason why your CSS is broken is that you specified a base URL of ./. You should instead use the destination URL of your site: https://capstone-projects-2020-spring.github.io/iASL-iOS/

[ApplebaumIan]

You should instead use the destination URL of your site: https://capstone-projects-2020-spring.github.io/iASL-iOS/

That makes sense! Would this look like:

- name: Generate Documentation
  uses: Applebaumian/swift-doc@master
  with:
    inputs: "ImageClassification"
    module-name: iASL
    format: "html"
    output: "Documentation"
    base-url: "https://capstone-projects-2020-spring.github.io/iASL-iOS/"

Answered my own question 🤣 it works!!! 🎉🎉

[ApplebaumIan]

Thanks for all of the help @mattt and everyone! Really looking forward to all of the updates in the future!!

[mattt]

@ApplebaumIan My pleasure! Thanks for helping us troubleshoot everything. Again, really happy that everything is working for you now.

Since the issue appears to be resolved, I'm going to close this thread. Please let me know if you run into any other issues with swift-doc.

[slashmo]

That's probably because installing swift-doc via Homebrew automatically installs GraphViz as a dependency. Same for the swift-doc GitHub Action, which comes with everything needed.
@mattt

Are you sure the GitHub Action comes with GraphViz installed? For me, the workflow adds warning annotations indicating that it’s not installed in the PATH: https://github.com/slashmo/swift-w3c-trace-context/actions/runs/247883058

[MaxDesiatov]

It does not, I've opened #180 for this. Also, the swift-doc GitHub Action still generates docs that are readable only by the root user, so there's still a need to add this step:

      - name: Update Permissions
        run: 'sudo chown --recursive $USER Documentation'

@mattt should this issue be reopened until the permissions issue is resolved, or would you like me to create a new one?