Nbdev tutorial: GH-Pages build fails: "missing expected setting: description"

nbdev
1

Hi, I’m following the nbdev tutorial having started from the template, and now have entered and saved the info for my GitHub Pages page, but then the tutorial reads,

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.

Uh…going back to my main repo page… Where’s that? I don’t see any place to click “edit”. If I click the little gear icon next to “About”, then I can edit the description I already gave, and it looks like the Pages url is already there, but…

The page never successfully builds. Looking under Actions, it still seems to be looking for a “description” string,…I think:

Log (my repo is named “mrspuff”):

Successfully installed MarkupSafe-1.1.1 Send2Trash-1.5.0 argon2-cffi-20.1.0 attrs-20.3.0 backcall-0.2.0 bleach-3.3.0 cffi-1.14.5 decorator-4.4.2 defusedxml-0.7.1 entrypoints-0.3 fastcore-1.3.19 fastrelease-0.1.11 ghapi-0.1.16 importlib-metadata-3.8.1 ipykernel-5.5.0 ipython-7.16.1 ipython-genutils-0.2.0 ipywidgets-7.6.3 jedi-0.18.0 jinja2-2.11.3 jsonschema-3.2.0 jupyter-1.0.0 jupyter-client-6.1.12 jupyter-console-6.4.0 jupyter-core-4.7.1 jupyterlab-widgets-1.0.0 mistune-0.8.4 nbconvert-5.6.1 nbdev-1.1.13 nbformat-5.1.2 notebook-6.3.0 packaging-20.9 pandocfilters-1.4.3 parso-0.8.1 pexpect-4.8.0 pickleshare-0.7.5 prometheus-client-0.9.0 prompt-toolkit-3.0.18 ptyprocess-0.7.0 pycparser-2.20 pygments-2.8.1 pyparsing-2.4.7 pyrsistent-0.17.3 python-dateutil-2.8.1 pyyaml-5.4.1 pyzmq-22.0.3 qtconsole-5.0.3 qtpy-1.9.0 six-1.15.0 terminado-0.9.3 testpath-0.4.4 tornado-6.1 traitlets-4.3.3 typing-extensions-3.7.4.3 wcwidth-0.2.5 webencodings-0.5.1 widgetsnbextension-3.5.1 zipp-3.4.1
Obtaining file:///home/runner/work/mrspuff/mrspuff
    ERROR: Command errored out with exit status 1:
     command: /opt/hostedtoolcache/Python/3.6.13/x64/bin/python -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/home/runner/work/mrspuff/mrspuff/setup.py'"'"'; __file__='"'"'/home/runner/work/mrspuff/mrspuff/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /tmp/pip-pip-egg-info-s1ug0pzw
         cwd: /home/runner/work/mrspuff/mrspuff/
    Complete output (5 lines):
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/home/runner/work/mrspuff/mrspuff/setup.py", line 13, in <module>
        for o in expected: assert o in cfg, "missing expected setting: {}".format(o)
    AssertionError: missing expected setting: description
    ----------------------------------------
WARNING: Discarding file:///home/runner/work/mrspuff/mrspuff. Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.
Error: Process completed with exit code 1.

But my GitHub page has a description, so…what’s the problem? (I thought I followed the instructions verbatim.)

Is it possible that this part of the tutorial is out of order? That the “description” it’s looking for comes later, after we (next in the tutorial) also edit settings.ini?

2

It seems that ignoring this error for and continuing into the next set of instructions, and adding a “description” line in settings.ini gets us past that error, but then we find a new GitHub Actions build error:

...
Obtaining file:///home/runner/work/mrspuff/mrspuff
    ERROR: Command errored out with exit status 1:
     command: /opt/hostedtoolcache/Python/3.6.13/x64/bin/python -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/home/runner/work/mrspuff/mrspuff/setup.py'"'"'; __file__='"'"'/home/runner/work/mrspuff/mrspuff/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /tmp/pip-pip-egg-info-ljjnrhx4
         cwd: /home/runner/work/mrspuff/mrspuff/
    Complete output (2 lines):
    running egg_info
    error: Invalid distribution name or version syntax: -lib-name--0.0.1
    ----------------------------------------
WARNING: Discarding file:///home/runner/work/mrspuff/mrspuff. Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.
Error: Process completed with exit code 1.
3

The error is that you didn’t fill out the description in settings.ini

4

Your library has to have a valid python library name. No dashes only underscore

5

Ok…so then three things:

  1. The tutorial should be edited to reflect that the Pages won’t build until the next section (editing settings.ini) is completed.
  2. When I went ahead and added the description to settings.ini, I get the second error I listed above.
  3. I stated my library name: “mrspuff”. Where are the dashes or underscores in that?
    Link to Actions build page.
6

Do you have a valid version number? Doesnt the tutorial say to fill out settings.ini completely before proceeding?

7

I was looking at this specifically

image
image1170×2532 377 KB

8

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?

9

Maybe link to your repo? Might make it easier for me to take a look :). I’m just guessing based on your error messages

10

The “^Actions build link” I posted above links to my repo.

Which is https://github.com/drscotthawley/mrspuff

11

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.

1 Like
12

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 and git 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'
13

Green Light! :slight_smile: 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 and git 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

…?

14

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. (?)

15

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?

16

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/

17

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?

18

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.

19

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?

20

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