Advice using doctr with jekyll?

[kyleniemeyer]

So, I am trying to use doctr with jekyll on my GitHub Pages-based site; I have a custom jekyll plugin, so I can't just rely on the built-in jekyll support.

This is complicated by the fact that this is a user page (i.e., the repo is "orgname.github.io"), so it must be built from the master branch.

I haven't seen any examples that use jekyll with doctr, so I've mostly hacked together the .travis.yml:

sudo: false
# Doctr requires python >=3.5
language: ruby
cache: bundler

# This gives Doctr the key we've generated
env:
  global:
    - secure: xxx

before_script:
  - sudo apt-get update
  # We do this conditionally because it saves us some downloading if the
  # version is the same.
  - wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
  - bash miniconda.sh -b -p $HOME/miniconda
  - export PATH="$HOME/miniconda/bin:$PATH"
  - hash -r
  - conda config --set always_yes yes --set changeps1 no
  - conda config --add channels conda-forge
  - conda update -q conda
  # Useful for debugging any issues with conda
  - conda info -a
  - conda create -q -n test-environment python=3.6 doctr
  - source activate test-environment

install:
  - bundle install

# This is the script to build the docs on travis, then deploy
script:
  - set -e
  - bundle exec jekyll build
  - doctr deploy --built-docs _site --branch-whitelist source --deploy-branch-name master .

I'm trying to have the website source on the source branch and then the content built in _site will be in the master branch for Github Pages. I added a .nojekyll file so that GitHub Pages doesn't try to build everything. Right now, the master branch has all of the source files as well.

However, I can't seem to get this to work. Any suggestions?

[kyleniemeyer]

Oh! I think I just got it to work. I had to add "Gemfile.lock", "Gemfile" to my exclude list in the jekyll _config.yml.

[asmeurer]

Anything to be done on our side (docs or otherwise)?

[kyleniemeyer]

I think it would be helpful to have some tips or this use case—it may not be super common, but it there were some non-obvious bits:

• How to use a combined language environment (doctr needs Python, but jekyll needs Ruby). I just settled on conda, but I'm not sure if my approach is best.
• For a user/organization page ("name".github.io), the website source files have to be on master, so the actual source code needs to be on a different branch.
• I needed a .nojekyll file so that GitHub Pages didn't automatically build the site

[asmeurer]

doctr does create .nojekyll automatically, but only when it creates a gh-pages branch from scratch. Since you are using a .github.io repo this doesn't apply.

I thought we had some stuff in the docs about .github.io pages but I guess we don't.

[ocefpaf]

@kyleniemeyer and @asmeurer do you have any advice for me in https://github.com/oceanhackweek/oceanhackweek.github.io

I created the source branch and followed the docs. Added the .nojekyll to master, made source the default branch, and removed .travis.yml from master. The only thing I did not do was to clean up the master branch (should I?). The CIs are passing but the page is not published.

[asmeurer]

This is why it didn't push https://travis-ci.org/github/oceanhackweek/oceanhackweek.github.io/builds/668978759#L2494.

[asmeurer]

I would clear master if you want it to be your gh-pages branch. Even if it doesn't cause problems, it can confuse people (you can also put a README in master telling them that they should use source).

[ocefpaf]

This is why it didn't push https://travis-ci.org/github/oceanhackweek/oceanhackweek.github.io/builds/668978759#L2494.

Argh! I've been bitten by this before. I always assume the first time it will push whatever as "new" but there is nothing really new.

I would clear master if you want it to be your gh-pages branch. Even if it doesn't cause problems, it can confuse people (you can also put a README in master telling them that they should use source).

I will once the setup is working. Thanks for the tip.

[ocefpaf]

OK. I cleared master and made a modification. Somehow I still get the The docs have not changed. Not updating message :-/

edit:

Looks like my leftover config in travis.yml had the lines:

doctr:
  require-master: true

and that was the problem. Also, I had to remove the README.md from the root directory b/c GH was confused and did not render the site.

Thanks @asmeurer!

[asmeurer]

Glad to hear you figured it out.

Also, I had to remove the README.md from the root directory b/c GH was confused and did not render the site.

You might be able to fix that by modifying the Jekyll config https://jekyllrb.com/docs/configuration/. I haven't used Jekyll before beyond the default GitHub config, but it sounds like you can move the sources to a subdirectory and set source.