Notebooks still not showing up

[nilshempelmann]

@tlvu @fmigneault

gitinclude seems to be running https://travis-ci.org/github/bird-house/birdhouse-docs/builds/733414708 notebooks are fetched but they are not showing up: https://birdhouse.readthedocs.io/en/latest/tutorial_finch.html

local compilation is running fine.

[tlvu]

@nilshempelmann not sure why you still mention gitinclude, I thought we do not use gitinclude anymore since PR https://github.com/bird-house/birdhouse-docs/pull/54

As for why notebooks are not showing up on RTD, here's the matching build log https://readthedocs.org/api/v2/build/12043957.txt

We see a massive amount of WARNING, some sample below:

WARNING: failed to reach any of the inventories with the following issues:
intersphinx inventory 'https://github.com/bird-house/pelican/objects.inv' not fetchable due to <class 'requests.exceptions.HTTPError'>: 404 Client Error: Not Found for url: https://github.com/bird-house/pelican/objects.inv

/home/docs/checkouts/readthedocs.org/user_builds/birdhouse/checkouts/latest/docs/source/guide_WPS.rst:23: WARNING: toctree contains reference to nonexisting document '_gitext/https_github_com_bird_house_cookiecutter_birdhouse_git/docs/source/dev_guide'
/home/docs/checkouts/readthedocs.org/user_builds/birdhouse/checkouts/latest/docs/source/guide_WPS.rst:27: WARNING: Error in "gitinclude" directive:
2 argument(s) required, 1 supplied.

.. gitinclude:: https://github.com/bird-house/cookiecutter-birdhouse/blob/master/%7B%7Bcookiecutter.project_repo_name%7D%7D/docs/source/dev_guide.rst
/home/docs/checkouts/readthedocs.org/user_builds/birdhouse/checkouts/latest/docs/source/guide_WPS.rst:115: WARNING: Error in "code-block" directive:
maximum 1 argument(s) allowed, 2 supplied.

/home/docs/checkouts/readthedocs.org/user_builds/birdhouse/checkouts/latest/docs/source/projects.rst:20: WARNING: toctree contains reference to nonexisting document '_gitext/https_github_com_Ouranosinc_pavics_sdi_git/docs/source/arch/backend'

_gitext/https_github_com_nilshempelmann_climdatatutorial_git/docs/source/notebooks/index.rst:14: WARNING: toctree contains reference to nonexisting document 'ClimateDataAccess'
_gitext/https_github_com_nilshempelmann_climdatatutorial_git/docs/source/notebooks/index.rst:14: WARNING: toctree contains reference to nonexisting document 'CMIP_resolution'

_gitext/https_github_com_Ouranosinc_raven_git/docs/source/notebooks/index.rst:11: WARNING: toctree contains reference to nonexisting document 'running_hmets'
_gitext/https_github_com_Ouranosinc_raven_git/docs/source/notebooks/index.rst:11: WARNING: toctree contains reference to nonexisting document 'running_gr4jcn'

WARNING: autodoc: failed to import process 'processes.RavenProcess' from module 'raven'; the following exception was raised:
No module named 'raven'
WARNING: autodoc: failed to import process 'processes.RavenGR4JCemaNeigeProcess' from module 'raven'; the following exception was raised:
No module named 'raven'

I am not sure what the build should look like but are you trying to pull notebooks from many different repos? Seems the relative reference to those external repos are not fully resolving.

And when they resolve, all the imports from the different notebooks are blowing up. We had the same problem with Raven, the solution was using mock import https://github.com/Ouranosinc/raven/blob/58e8978375565fa095e0ec8ae1bf81dc25741f94/docs/source/conf.py#L60-L70

If we just take a step back, pulling all the different notebooks here is sure convenient but you'll need to duplicate all the various oddities that each repo have to do to make their RTD build works. Why not just link to the other RTD of each repo?

RTD also have a concept of sub-projects that allows integrated search from the main project, ex: https://pavics-sdi.readthedocs.io/en/latest/search.html?q=cdd_Indicator_Process&check_keywords=yes&area=default this search performed from Pavics-SDI is able to find the info from the Finch sub-project. Raven and Finch are already sub-projects of Pavics-SDI. Not sure they can be sub-projects under another project, this one.

[tlvu]

@nilshempelmann Also WARNING in docs build means silent doc build error which means silent partial broken documentation. I've had it several times that I am feed up so I turn WARNING into error for both RTD and Travis-CI build here https://github.com/bird-house/cookiecutter-birdhouse/pull/96. If you ever go that route, prepare lots of time to handle all the WARNING.

[nilshempelmann]

@tlvu understand and agree with your argumentation. Thanks for all the infos. I will see what can be solved with mock import, solving the rest with simple links to the original places.

[nilshempelmann]

@tlvu Its actually finch and raven blowing it up. So following your advice, I replaced the gitinclude to a simple link to the original subproject documentation.