search

drdoctr / doctr

A tool for automatically deploying docs from Travis CI to GitHub pages.
https://drdoctr.github.io
MIT License
107 stars 30 forks source link

Consider always adding .nojekyll #361

Open Meteodan opened 4 years ago

Meteodan commented 4 years ago

Hi all, I'm trying to set up a website for my repository at http://Meteodan.github.io/arpsEnKFtools/

I am very new to deploying web sites on GitHub and am relatively new to "respectable" open source python-based workflows in general.

I have been using the "Scientific Python Cookiecutter" guide to deploy the site for my repository, and they recommend using doctr. The instructions I've been following are here: https://nsls-ii.github.io/scientific-python-cookiecutter/publishing-docs.html

I already have Travis-CI set up for the site, and the build seems to work. However, the site does not display the default "sphinx_rtd_theme" despite having it set properly in the conf.py file. The build information on Travis doesn't seem to show anything related to this problem, so I can't figure out where it is failing.

Forgive me if this is the wrong place to ask this, as it is quite likely that I am just missing something obvious. But, I would appreciate any help you could give.

Meteodan commented 4 years ago

Ok, I solved the problem. My gh-pages branch (which already existed) did not have a ".nojekyll" file in the root. I was under the impression that doctr created this file, but perhaps it only does that if the gh-pages branch doesn't already exist? In any case, I solved the problem by deleting the gh-pages branch and letting doctr re-create it. Now the theme shows up properly.

asmeurer commented 4 years ago

Yes, perhaps it's possible for doctr to do better here. IIRC we don't create it except when creating gh-pages because some people actually do use Jekyll (IMO GitHub should have made nojekyll the default, but that ship has sailed).

Meteodan commented 4 years ago

Thank you for the reply! Should I close this issue or would you prefer we leave it open in case there's something you wanted to change in response to it?

asmeurer commented 4 years ago

I think we should consider always adding .nojekyll, with a flag to tell it not to if you don't want that.