Doesn't have a title: no link will be generated

[jetheurer]

I have an issue where the following warning comes up:

WARNING: toctree contains reference to document 'example' that doesn't have a title: no link will be generated

Where example is the name of my notebook example.ipynb

and this is the command I run: python3 -m sphinx -b html -j 4 docs/source/ $BUILD

When looking at the generated files, I dont get the link to example in my documentation.

My toctree looks like this:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   example.ipynb
   readme
   modules

To clarify, the html file: example.html builds, but the link in index.rst is dropped.

[jetheurer]

This seems related to: https://stackoverflow.com/questions/55297443/including-of-notebook-with-nbsphinx-fails

[jetheurer]

Here is a minimal example: minimal_nbsphinx.zip

Please run using bash build.sh

Relevant error: WARNING: toctree contains reference to document 'test' that doesn't have a title: no link will be generated

[jetheurer]

For those that run into this again,

Here is a minimal working notebook:

{
 "cells": [
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "# Test"
    ]
   }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}

The most relevant component being:

    "source": [
     "# Test"
    ]

All notebooks need a markdown section with a title!

[TCACastelijns]

I know this issue is closed, but I get still get the error above. Even if my notebooks contains titles.

My index.rst contains of

- predict.ipynb
- train.ipynb
- evaluate.ipynb

I wrote documentation for predict step with markdown and code examples:

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Predict"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# For running this notebook\n",
    "import sys\n",
    "sys.path.append('../..')\n",
    "\n",
    "# Standard\n",
    "from datetime import timedelta, datetime\n",
    "import pandas as pd\n",
    "import pytz\n",
    "import re\n",

.....

 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}

The train and evaluate scripts only contains a title and one line of markdown.

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "bcf5baf7",
   "metadata": {},
   "source": [
    "# Evaluate"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4599130f",
   "metadata": {},
   "source": [
    "Evaluate's pipeline docs"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}

If I build the documenation I get the following warnings:

/docs/_src/index.rst:11: WARNING: toctree contains reference to document 'predict' that doesn't have a title: no link will be generated

But the train.ipynb and evaluate.ipynb notebooks doesn't have any problems and are connected to the index. Anyone any idea how to solve this?

[mgeier]

@TCACastelijns Do you get any other warnings?

This sounds a bit like #549 which was fixed in #552 and released in nbsphinx version 0.8.3.

[TCACastelijns]

@mgeier : Thanks for this hint. Indeed I also got the long line warning:

/docs/_src/predict.ipynb:: WARNING: Line 810 exceeds the line-length-limit.
/docs/_src/predict.ipynb:: WARNING: Each notebook should have at least one section title

I upgraded to nbsphinx version 0.8.3 and that fixed the problem!

[theRealSuperMario]

For those who are still running into this, you also need to make sure that .ipynb is not added to the source_suffix list.

See here https://stackoverflow.com/a/70474616/10045897

[pique-b]

@jetheurer I am facing exactly the same issue as discussed here. Currently I have nbsphinx 0.9.3 installed. I have tried to use Jupyter Notebook files, one each from that created on Colab as well as one created on my local machine. In both the instances I have faced the same problem.

I tried to add title to the files by opening them in TextEdit app and added like:

  ...
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "title": "My Title",        <-- Here
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
  ...

However it has not worked.

If I use # My_Test (I replicated the one explained by @TCACastelijns ), it throws the following error:

Notebook error:
PandocMissing in file_name.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html
make: *** [html] Error 2

However, pandoc ver. 2.3is already installed.

One other clarification: How does a Notebook file miss out on adding the Title in the file if that is so important an element?

A guidance would be much appreciated.

[mgeier]

@pique-b Please note that the term "title" is ambiguous here.

It does not mean the title field in the Jupyter notebook metadata.

It means the title in the sense of "the first section title of the page".

The Pandoc error is unrelated, maybe you have to add it to the PATH?

Even if you have it installed, the Python installer might still not be able to find it.