[BUG] [etoc] missing index.html written as redirect to 'welcome.html' build note

[da5nsy]

@aleesteele: #2883 (comment) :

Tagging @da5nsy here, getting the error [etoc] missing index.html written as redirect to 'welcome.html' build error? Not sure why that might be the case?

This does not cause the CI to fail, so not urgent, but...

• My best guess is that that warning occurs because of this issue: changing the root entry in _toc.yml has no effect at build executablebooks/sphinx-external-toc#50 in which case we would need to clear out the cache at netlify.

• My second best guess is that it is because we have root: and format: in the opposite order in our TOC vs the JB docs.

[TheAbstract]

FYI: Hey @da5nsy I was trying to reproduce this error; ran a build on latest main and didn't get any error.

theabstract at website on main
❯ jupyter-book build .
Running Jupyter-Book v0.13.0
Source Folder: /Users/theabstract/foss/the-turing-way/book/website
Config Path: /Users/theabstract/foss/the-turing-way/book/website/_config.yml
Output Path: /Users/theabstract/foss/the-turing-way/book/website/_build/html
Running Sphinx v4.5.0
loading translations [en]... done
[etoc] Changing master_doc to 'welcome'
loading pickled environment... failed
failed: source directory has changed
checking bibtex cache... out of date
parsing bibtex file /Users/theabstract/foss/the-turing-way/book/website/_bibliography/references.bib... parsed 158 entries
myst v0.15.2: MdParserConfig(renderer='sphinx', commonmark_only=False, enable_extensions=['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist'], dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', disable_syntax=[], url_schemes=['mailto', 'http', 'https'], heading_anchors=None, heading_slug_func=None, html_meta=[], footnote_transition=True, substitutions=[], sub_delimiters=['{', '}'], words_per_minute=200)
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 328 source files that are out of date
updating environment: [new config] 328 added, 0 changed, 0 removed
reading sources... [100%] welcome                                                                                                                             
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] welcome                                                                                                                              
generating indices... genindex done
writing additional pages... search done
copying images... [100%] figures/theturingway-chapters.jpg                                                                                                    
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

===============================================================================

Finished generating HTML for book.
Your book's HTML pages are here:
    _build/html/
You can look at your book by opening this file in a browser:
    _build/html/index.html
Or paste this line directly into your browser bar:
    file:///Users/theabstract/foss/the-turing-way/book/website/_build/html/index.html            

===============================================================================

I also ran a build on the commit hash of the mentioned PR c0216fe, still didn't get that error. 🤷🏾
So I'm assuming this was resolved in some other PR, or I'm probably missing something.

• Anyway, this also might be related dirhtml build index.html does not redirect to root folder #1414, in case the issue needs to be worked on.

[da5nsy]

Oh cool thanks @TheAbstract! That's very useful info!

It's not been fixed (see https://github.com/alan-turing-institute/the-turing-way/actions/runs/3595245737/jobs/6054502025) and so this points to it being a cache thing.

[TheAbstract]

Oh okay I see it now, was able to reproduce it building from this commit c0216fe, must have been looking at the wrong terminal or something 🤦🏾‍♂️.

The HTML pages are in _build/html.
[etoc] missing index.html written as redirect to 'welcome.html'

[da5nsy]

I don't think it's a project-specific thing - I just built a totally new and fresh book from scratch and this note was still in there 🤷 (but then went away when I changed the title of one page and rebuilt it) - must be a jupyterbook thing...

[JimMadge]

I can reproduce this message.

Having a little look...

_build/html/index.html

<meta http-equiv="Refresh" content="0; url=welcome.html" />

_build/html/welcome.html

<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

    <title>Welcome &#8212; The Turing Way</title>
...

So, like the message suggests index.html has been created and redirects to welcome.html.
I suppose this is because there is a welcome.md but no index.md.
I'm not really sure if having something at index is a requirement or just convention.
Maybe jupyter-book expects and index and creates a simple file to redirect to the book's root if there isn't one?

[JimMadge]

If I create an index.md and build the book. The [etoc] message does not appear.

When looking at the rendered html the homepage (link on The Turing Way logo) is now index.md.

[da5nsy]

Do you propose we do something to "fix" this @JimMadge or let it be?

[JimMadge]

It's odd because I don't think it is really a bug, at least not in the book, but it is causing confusion so I think it would be good to try to stop the message being printing without creating too much disruption. One proposal in #2994