Add docs workflow

[eliotwrobson]

One of the last PRs for #160! I think all that needs to be done is set the publish source branch for this page is gh-pages (per the instructions here: https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions).

I haven't played around with this too much, so I can't quite verify that it works. I think the way to handle it might be to have the workflow run on pushes to develop, then check that the github pages is working as expected. Then, we can remove that trigger once everything is set up. @caleb531 what are your thoughts? This might require some fiddling on your end.

[coveralls]

coverage: 99.64%. remained the same
when pulling d4b4377 on eliotwrobson:docs_workflow
into 3444b17 on caleb531:develop.

[caleb531]

@eliotwrobson Yep, looks good to me! And yes, I've always figured that as the sole repository owner, I'm the one able to set up the GitHub Pages site.

Here's a screenshot of what's available to me from settings. I can either have the site deployed from a branch, or via GHA (the latter of which definitely seems more flexible and the way to go).

[eliotwrobson]

@caleb531 Now that I think about it, I think the GHA setup on the screenshot you posted just creates a workflow file like the one included here. So I think if this gets merged you can manage it from the page you see there, but it also might just work? I'm going to go ahead and merge this and see what the workflow spits out. If it starts acting weird, I'll play with it a little bit on my fork to see what's going on.

[eliotwrobson]

@caleb531 I figured it out! After playing with it on my fork, it looks like this workflow has a bot commit to a branch called gh-pages. If you go to the github pages settings and set it the same way as the screenshot below, it should work:

You can see the live version of the docs on my fork here: https://eliotwrobson.github.io/automata/

[caleb531]

@eliotwrobson Oh interesting. But if that's the case, then why does that Settings page make it seem like "GitHub Actions" and "Deploy from a branch" are two separate sources? I suppose the former allows you to update your documentation from a branch other than gh-pages (meaning you never have to interact with gh-pages directly), whereas the latter requires manually committing/merging to the gh-pages branch?

I ask because ultimately, I want to ensure the docs site will always reflect the latest docs/ on the main branch (develop for now). So I guess the GHA workflow is simply designed to keep the gh-pages branch in sync with whatever source branch we define (like main or develop)?

[eliotwrobson]

@caleb531 I think that's the idea. Setting "Deploy from a branch" doesn't include a workflow to automate the deployment, but using GitHub Actions does. In any case, I couldn't find a workflow in the marketplace under the actions tab that was configured for mkdocs, and we get the same automated deployment from the current configuration anyway. So I think this is the way to go for now.

EDIT: Yes, the current GHA workflow will keep the docs site updated with the latest docs built from the main branch. It should be straightforward to switch to the pure-actions deployment if we ever find a workflow that's set up for mkdocs.

[caleb531]

@eliotwrobson Okay perfect, that all sounds good to me. Also, I think the workflow run has failed since we merged. See https://github.com/caleb531/automata/actions/runs/7365798293/job/20047438306

  File "/opt/hostedtoolcache/Python/3.12.1/x64/lib/python3.12/site-packages/mkdocs_macros/__init__.py", line 7, in <module>
    from .context import fix_url, is_relative as is_relative_url
  File "/opt/hostedtoolcache/Python/3.12.1/x64/lib/python3.12/site-packages/mkdocs_macros/context.py", line 19, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

Could you please investigate?

[eliotwrobson]

@caleb531 the workflow run failed, but I fixed it in the latest commit on develop: https://github.com/caleb531/automata/tree/develop

[caleb531]

@eliotwrobson Oh I see now. Although the repository Settings page doesn't seem to have picked up the workflow, given that it still reads "Workflow details will appear here once your site has been deployed." Perhaps we're missing some important definitions or fields in the workflow?

It seems like the starter workflows all contain an environment definition:

environment:
  name: github-pages
  url: ${{ steps.deployment.outputs.page_url }}

Perhaps this is what we're missing?

[eliotwrobson]

@caleb531 you have to change the source from "GitHub Actions" to "Deploy from a branch" as in my earlier comment: #195 (comment)

After that is first change, it should show more information.

[caleb531]

@eliotwrobson I see now. I made the changes you asked:

Making the above changes seems to have triggered a "pages build and deployment" job, which has unfortunately failed for some reason:

https://github.com/caleb531/automata/actions/runs/7366279616

Configuration file: none
To use retry middleware with Faraday v2.0+, install `faraday-retry` gem
  Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss':
                    No such file or directory @ dir_chdir - /github/workspace/docs
/usr/local/bundle/gems/jekyll-sass-converter-1.5.2/lib/jekyll/converters/scss.rb:86:in `chdir': No such file or directory @ dir_chdir - /github/workspace/docs (Errno::ENOENT)

[eliotwrobson]

@caleb531 hmmm that's unusual. It's working on my fork, and I'm not sure why the deploy workflow includes a jekyll build step. Let me investigate what's going on.

[eliotwrobson]

@caleb531 my mistake, I copied the wrong image! The directory should be set to / (root) instead of /docs.

Since I think that should resolve the issue, I'll get to work on the last develop PR that will update the documentation links to what should be the URL for the new site.

[caleb531]

@eliotwrobson Ah, excellent, that did the trick! The documentation site is now live!
https://caleb531.github.io/automata/

The only thing that's immediately apparent to me is that the theme seems to have changed compared to the latest local version from develop, so the sidebar is not always-visible. Do you have any idea what changed and how we can ensure the same theme (preferably the one with the permanent sidebar) is used in both local and CI?

Local Site (mkdocs serve from develop)

Live Site (https://caleb531.github.io/automata/)

[eliotwrobson]

@caleb531 awesome! For the sidebar, maybe there's a weird caching thing going on? I just opened the page and I see the sidebar:

[eliotwrobson]

@caleb531 actually, I think it depends on the width in the screen resolution? I'm not sure if there's a way to configure this behavior.

[caleb531]

@eliotwrobson You know what, you're absolutely right! I just realize that my localhost page was slightly zoomed in (you can even see the zoom icon in the right-hand side of the address bar in my original screenshot 😅). No worries about that, then!