build from /docs directory

[rtreddick]

Hi, I want to build my docs website from the the ./docs directory in my project. I started by trying to use the just-the-docs-template and moving all the files (except the .github/workflows directory and its contents) to a directory at ./docs. I can't figure out how to modify the build and deploy workflow to look to the docs directory instead of the project root.

I may be trying to use the template in an unintended way, or maybe there is a really simple solution to what I'm trying to achieve. Any guidance would be helpful.

[mattxwang]

Thanks for submitting a question @rtreddick! This is certainly a common use-case, and I'm sure others are wondering the same thing.

I can't figure out how to modify the build and deploy workflow to look to the docs directory instead of the project root.

If I'm understand your problem correctly, there's a handful of ways to do this; the suggested way is probably to change the default working directory for an Action, ex in pages.yml:

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: docs
    steps:
# ...

You could also cd into docs for every command you run; this is a bit hacky, but makes it obvious to readers what's going on/

Let me know if this helps / if you have a follow-up!

[rtreddick]

Hi @mattxwang! Thanks for the quick response. I updated the default working directory for the build job, but now I'm seeing this:

Bundler can't find Jekyll for some reason. Right now I'm working in a public practice repo. Here is the run: https://github.com/rtreddick/just-the-docs-practice/actions/runs/4282219381

I also tried passing in a --source parameter to Jekyll build command, while not changing the default working-directory. Then I get "Could not locate Gemfile or .bundle directory." I tried setting the source path various ways including docs, /docs, ./docs, just-the-docs-practice/docs, etc.

As I'm writing this response, I just looked back at the Ruby Setup job which appeared successful but noticed this:

It could not find the gemfile because it was not at root I'm guessing. In the docs for the ruby/setup-ruby action it looks like there might be some config to point it to the correct path. I will take a look at that this morning and post the result. Please let me know if you've got any other ideas/advice.

Thanks!

[rtreddick]

I finally got it to work! Here are the steps I took:

• change default working-directory for the runner as you suggested

• pass in a working-directory param to the ruby/setup-ruby action

    - name: Setup Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: '3.1' # Not needed with a .ruby-version file
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically
      cache-version: 0 # Increment this number if you need to re-download cached gems
      working-directory: '{{ github.workspace }}/docs'
  

• pass in a path param to actions/upload-pages-artifact action

    - name: Upload artifact
       # Automatically uploads an artifact from the './_site' directory by default
       uses: actions/upload-pages-artifact@v1
       with:
         path: "docs/_site/"
  

[rtreddick]

So interestingly, changing the default run working-directory as shown below didn't appear to change the github.workspace variable. You can see under the setup-ruby action in the snippet above that I still had to append "/docs" to get the path I was looking for.

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: docs
    steps:
# ...

[mattxwang]

Ah! First of all, glad you got it to work! I didn't realize that it was more complicated than just setting the working-directory, sorry about that. I'm curious why Actions doesn't automatically forward the working directory to setup-ruby (there must be a good reason). I appreciate you diving in to this, I'm sure it'll be helpful for others.

Follow-up Q: do you think we should document this somewhere? If so, happy to accept a PR for this so others don't have the same frustration in the future!

[rtreddick]

Thanks for following up. Yeah, I can document this! I will take a look at the docs this weekend and think about where it might best fit and put it in a PR. Or if you have any suggestions, let me know.

…

On Tue, Feb 28, 2023 at 11:21 AM Matt Wang ***@***.***> wrote: Ah! First of all, glad you got it to work! I didn't realize that it was more complicated than just setting the working-directory, sorry about that. I'm curious why Actions doesn't automatically forward the working directory to setup-ruby (there must be a good reason). I appreciate you diving in to this, I'm sure it'll be helpful for others. Follow-up Q: do you think we should document this somewhere? If so, happy to accept a PR for this so others don't have the same frustration in the future! — Reply to this email directly, view it on GitHub <#1183 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMLXAKUJ6PB6ERQWEIVNK3TWZYQXFANCNFSM6AAAAAAVIRQLXE> . You are receiving this because you were mentioned.Message ID: ***@***.*** .com>

[mattxwang]

Thanks for volunteering to document this! I have two thoughts on where it could go, both in the template:

• in the README/index, i.e. user-facing for everyone
• in the Actions file itself, i.e. for people who are looking to do some configuration

In your case, which did you do first? I think the goal is to have the information in the "natural" troubleshooting path for our users.

[rtreddick]

Hey @mattxwang, I finally put in that PR. When I was first trying to use the template, I started by reading the template home page (defined by index.md file) and followed the 'use the template' link, which prompted me to create a new repo from the template. It made sense to me then to add a note right beneath that to redirect those users who want to use an existing repo. I added the section "Hosting your docs from an existing project repo" to the README. I left some more notes in the PR. Happy to incorporate any feedback you have. I didn't make any notes in the pages.yml file itself, but we can do that if you think it's helpful.