Does Ginga readthedocs reflect latest dev version?

[pllim]

I was under the impression that https://ginga.readthedocs.org/en/latest/ reflects the latest dev version. However, I am unable to find any documentation on LineProfile plugin. Am I missing something?

[ejeschke]

I think the readthedocs.org sphinx documentation is not being automatically rebuilt on a github commit. I've manually triggered a rebuild, but this needs to be fixed. @cdeil or @bsipocz, you both seem to be well versed in the arts of travis ci. Any chance you could have a quick look at the .travis.yml and see if you see anything obvious?

[cdeil]

Readthedocs runs the sphinx build and puts up the HTML docs if it was successful. If there's another sphinx build on travis-ci, that is just for testing, it's not the case that travis-ci publishes the output html somewhere.

It looks like the sphinx builds on readthedocs work fine: https://readthedocs.org/projects/ginga/builds/ https://readthedocs.org/projects/ginga/builds/3475917/

If I build the docs locally and put LineProfile in the search field, also nothing is found. You have to look why LineProfile isn't part of the Sphinx API docs.

If someone has time to fix the Sphinx errors and warnings, that would be great!

$ python setup.py build_sphinx
running build_sphinx
creating /Users/deil/code/ginga/doc/_build
creating /Users/deil/code/ginga/doc/_build/doctrees
creating /Users/deil/code/ginga/doc/_build/html
Running Sphinx v1.3.1
loading pickled environment... not yet created
WARNING: 'default' html theme has been renamed to 'classic'. Please change your html_theme setting either to the new 'alabaster' default theme, or to 'classic' to keep using the old default.
building [mo]: all of 0 po files
building [html]: all source files
updating environment: 15 added, 0 changed, 0 removed
reading sources... [100%] quickref                                                                                                                                                     
/Users/deil/code/ginga/doc/WhatsNew.rst:17: ERROR: Unexpected indentation.
/Users/deil/code/ginga/doc/WhatsNew.rst:19: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/deil/code/ginga/doc/WhatsNew.rst:27: ERROR: Unexpected indentation.
/Users/deil/code/ginga/doc/WhatsNew.rst:28: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/deil/code/ginga/doc/manual/canvas.rst:76: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/deil/code/ginga/doc/manual/canvas.rst:77: WARNING: Block quote ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/deil/code/ginga/doc/manual/canvas.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] quickref                                                                                                                                                      
/Users/deil/code/ginga/doc/manual/developers.rst:43: WARNING: undefined label: fig2 (if the link has no caption the label must precede a section header)
/Users/deil/code/ginga/doc/manual/developers.rst:377: WARNING: undefined label: fig2 (if the link has no caption the label must precede a section header)
/Users/deil/code/ginga/doc/manual/operation.rst:112: WARNING: undefined label: preferences-zoom (if the link has no caption the label must precede a section header)
/Users/deil/code/ginga/doc/manual/operation.rst:171: WARNING: undefined label: preferences-autocuts (if the link has no caption the label must precede a section header)
/Users/deil/code/ginga/doc/manual/operation.rst:171: WARNING: undefined label: preferences-newimages (if the link has no caption the label must precede a section header)
/Users/deil/code/ginga/doc/manual/operation.rst:217: WARNING: undefined label: preferences-transform (if the link has no caption the label must precede a section header)
generating indices... genindex
writing additional pages... search
copying images... [100%] manual/figures/multidim-plugin.png                                                                                                                            
copying static files... WARNING: html_static_path entry '/Users/deil/code/ginga/doc/_static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 15 warnings.

[pllim]

@ejeschke , @cdeil , I fixed the warnings in #224

[pllim]

I can find "Line Profile" in the online documentation now, but that does not prove that it is being automatically updated on commit, since @ejeschke manually pushed an update earlier.

[ejeschke]

From @cdeil's comment I'm gathering that the problem seems to be that the automatic build should be coming from readthedocs's side. And the build there works, so it's rather something about setting some kind of flag there to automatically build on the github commit that I'm missing.

[pllim]

Looks like RTD is still not updating on its own, as I don't see changes from #224 reflected there. FYI.

[cdeil]

The last Ginga build on RTD succeeded: https://readthedocs.org/projects/ginga/builds/3475917/

If the HTML files on readthedocs are different from what you get locally, usually wiping the readthedocs build folder helps: http://docs.readthedocs.org/en/latest/faq.html#deleting-a-stale-or-broken-build-environment

Then start a new build at https://readthedocs.org/projects/ginga/builds/ and after ~ 5 min check if the HTML docs are OK.

I don't have permissions to do this for Ginga, @ejeschke, maybe you can do this?

[ejeschke]

It used to work fine for me to manually trigger a build. After @pllim's updates to the documentation it is now failing with:

Extension error:
Could not import extension numpydoc (exception: No module named numpydoc)

So I think we need to add a requirements file so that numpydoc gets installed.

[ejeschke]

Oh, and I did the "wipe" suggested by @cdeil first.

[cdeil]

Ah, I see, the error is here: https://readthedocs.org/projects/ginga/builds/3549306/

numpydoc (https://pypi.python.org/pypi/numpydoc) is listed in doc/conf.py: https://github.com/ejeschke/ginga/blob/master/doc/conf.py#L29

Probably numpydoc is not installed on RTD?

@ejeschke - Can you try adding a doc/rtd-pip-requirements file with a single line containing numpydoc, and then tell readthedocs to pip install the dependencies listed there via this web form?

https://readthedocs.org/dashboard/ginga/advanced/

[cdeil]

PS: I don't know why the issue shows up now ... I think readthedocs changed to docker containers or there might have been other changes in their setup that led to numpydoc being available earlier, but not now.

Also, I just remembered: numpydoc is probably not needed. Instead you should use the 'sphinx.ext.napoleon' extension in doc/conf.py, which supports the Numpy docstring standard and is now part of the Sphinx core package: http://sphinx-doc.org/ext/napoleon.html (i.e. no longer need to pip install a separate extension like numpydoc).

My suggestion would be to try switching to 'sphinx.ext.napoleon' first and see if that works for Ginga.

[pllim]

Thanks, @cdeil . Sorry for the inconvenience, @ejeschke . Please try to see if my fix in #245 will resolve this.

[ejeschke]

This indeed fixes the build, but it seems the build is still not triggered automatically by a commit. As far as I can tell on the RTD side everything looks good (especially since pressing the build button works fine now). I'll do a wipe and monitor the next couple of commits.

[ejeschke]

I checked the "webhooks and services" page on github settings and "ReadTheDocs" was not there. I've added it. This should kick off a doc build on a commit.

[ejeschke]

auto build is succeeding! Thank you everyone!