question about executing notebooks

[parmentelat]

I'm truly happy with my current setup:

• one index.rst that mentions the notebooks that I want to insert
• I use my own flavour of sphinx_ipypublish_all.extso that I no longer need to mess with Makefile's to compute and commit executed versions of the notebooks
• everything runs just smoothly down to readthedocs

there's just one little thing that puzzles me a little; when I run

sphinx-build -b html . _build/html

I can see messages like e.g.

ipypublish: converting notebook01.ipynb
ipypublish: converting notebook02.ipynb

it's all fine, but what puzzles me is that the list of notebooks that are dealt with in this way is not the list that I have in index.rst, its feels more like it's the whole set of notebooks in the directory

I'm asking because it's a bit of a hindrance, it would help in devel mode to be able to focus on one or a few specific notebook (by tweaking index.rst temporarily) ; is there anything I am doing wrong, is there something I can do to work around this (short of moving notebooks around, naturally) ?

thanks a lot anyway !

[chrisjsewell]

By default sphinx will convert ALL files it finds, with extensions it knows how to convert (in this case .rst and .ipynb). It is not goverened by the the index.rst, since you can also have files you don't want in the table of contents (see the :orphan: directive). If you don't wish for 1 or more files to be converted, you need to specify this in the conf.py, e.g. using exclude_patterns.

Note: it is a good idea to run sphinx-build in nit-picky mode, which will highlight issues like this: sphinx-build -b html -n . _build/html. Also going one step further, for example with the ipypublish documentation, I run the sphinx-build in Travis-CI with -nW (see here), which fails if there are any build warnings. This way I know the documentation will be built correctly, when deployed to readthedocs.