I was looking at this specifically
No. I don’t think so. I’m looking at https://nbdev.fast.ai/tutorial.html
Perhaps there’s a newer version of it elsewhere?
Here’s the section on GitHub Pages:
Github pages
The nbdev system uses jekyll for documentation. Because GitHub Pages supports Jekyll, you can host your site for free on Github Pages without any additional setup, so this is the approach we recommend (but it’s not required; any jekyll hosting will work fine).
To enable Github Pages in your project repo, click Settings in Github, then scroll down to Github Pages, and set “Source” to Master branch /docs folder. Once you’ve saved, if you scroll back down to that section, Github will have a link to your new website. Copy that URL, and then go back to your main repo page, click “edit” next to the description and paste the URL into the “website” section. While you’re there, go ahead and put in your project description too.
Now, there are also differences from what the tutorial shows and what my settings.ini
showed. For example, a number of my lines are already uncommented, and have values inside curly braces. The tutorial doesn’t show this.
I was thinking one could allow those curly-braced values to remain as they are, that they would be inferred from the main GitHub repo info. But …apparently not?
Maybe link to your repo? Might make it easier for me to take a look :). I’m just guessing based on your error messages
The “^Actions build link” I posted above links to my repo.
So, as a new user, I see “here’s how you set up GitHub Pages”,…and then when that doesn’t work, I get stuck there.
Apparently the intent was, “You shouldn’t expect GitHub Pages to actually build until you’ve completed this entire tutorial.” If the tutorial said that early-on, then I would’n’t have gotten / wouldn’t be stuck.
So think for now I’ll just stop checking to see if Pages built until I finish the rest.
Ok @hamelsmu , finished, added, committed and pushed. But failed again. Instead of…
Commit to Github
You can now check-in the generated files with
git add
,git commit
andgit push
. Wait a minute or two for Github to process your commit, and then head over to the Github website to look at your results.
…Actions is saying it can’t find my module, which has the same as the name of my repo, which is the name as in my settings.ini file…
[Latest Actions build]
(https://github.com/drscotthawley/mrspuff/runs/2210950216?check_suite_focus=true):
Run nbdev_test_nbs
testing /home/runner/work/mrspuff/mrspuff/index.ipynb
Error in /home/runner/work/mrspuff/mrspuff/index.ipynb:
An error occurred while executing the following cell:
------------------
#hide
from mrspuff.core import *
------------------
---------------------------------------------------------------------------
ModuleNotFoundError Traceback (most recent call last)
<ipython-input-1-c157f894b815> in <module>
1 #hide
----> 2 from mrspuff.core import *
ModuleNotFoundError: No module named 'mrspuff'
ModuleNotFoundError: No module named 'mrspuff'
Green Light! Looks like I missed a few generated files from the previous add & commit.
I wonder if there’s anything more explicit that could be written in the docs beyond just
You can now check-in the generated files with
git add
,git commit
andgit push
Like, would telling users to run the folliwng catch everything…?
git add <your-repo-name> *.ipynb docs README.md
git commit [ then write a message]
git push
…?
Ahhh. But the page still 404’s. GitHub Settings has the line:
Your site is having problems building: You have an error on line 1 of your
_config.yml
file. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#config-file-error.
uh…but that config file was either supplied in the template or generated via nbdev. I never touched it. (?)
Wait, the error it’s giving me about line 1 in my _config.yml
:
I didn’t create or edit any _config.yml
file. The one in docs/ was generated by nbdev_build_docs. So that script is producing the error?
Ok,the verdict seems to be: Anything inside curly braces in the config files doesn’t work (or wasn’t working for me).
So in docs/_config.yml, there are bunch of lines that the tutorial doesn’t tell you to edit, because it looks like someone wanted these to be able to infer from other parts of the repository…
My solution was, I went in and hand-overwrote all those curly-brace instances with my own strings (as with fastai/nbdev/docs/_config.yml), and then my page finally built: https://drscotthawley.github.io/mrspuff/
The idea is that the user would all the files that were generated, which you can see with
git status
Perhaps you would like to submit a PR to clarify this?
You shouldn’t have to edit _config.yaml
so that suggests something else is wrong. I would actually recommend starting over with a fresh repo to see if you can make everything work from scratch.
So, to clarify:. I just started this for the first time last night, starting from the latest template, and you’re saying… try all that again.
Ok, but before I do that, can you verify? Maybe I started from an outdated link? I was starting from this page and clicking on the link that reads:
“To create your new project repo, click here: nbdev template”
Was that wrong?
No thats right. Just make sure you edit settings.ini correctly, do not change the fields that it tells you to ignore, and make sure you checkin all your files, and you should not need to edit _config.yaml
if you are just using the github.io domain.
If you are using your own domain, then that is definitely a “special” situation but try the non special situation first to make sure it works for you
Ok, one thing I didn’t do last time was check the box for “Include add branches” when creating the repository.
Should I do that this time?
it doesn’t matter one way or the other
I you get confused, compare the settings.ini
and _config.yaml
in the fastai/nbdev
repo to your files, since that also uses a custom domain.
I believe you will also need a CNAME file as well in the /docs
folder (check the repo just as an example)
Oh sorry I guess you aren’t using a custom domain. So just ignore that part!
Yea, dude, I never did ANYTHING special. I just kept exactly to the tutorial. Nothing private, nothing custom.
Should be easy! I’m sure it will work now