Attempt to build documentation with Travis-CI #10911

olesyabar · 2017-11-20T16:45:51Z

This is attempt to solve #10895:

Added building documentation, using Travis Builds Doc jupyter/notebook#2808 as an example
Dropped support for Python 3.3 because Travis CI had issues building it ("The command "if [[ $GROUP == docs ]]; then make -C docs/ html; fi" exited with 2.") + saw that Travis CI had issue with Python 3.3 in jupyter/notebook@1ec12f7
Tests now produce warnings like "/home/travis/build/olesyabar/ipython/IPython/core/debugger.py:docstring of IPython.core.debugger.Pdb.do_q:3: WARNING: Unexpected indentation." but fixing the warnings is outside of this PR

@syutbai actively contributed to this during PyCon Canada sprinting

jzf2101 · 2017-11-20T17:02:42Z

@douglatornell can you confirm you also have these error?

jzf2101 · 2017-11-20T17:05:50Z

From what I can tell it looks like this could asking for a line break?

douglatornell · 2017-11-20T17:33:14Z

@jzf2101 Confirmed. Output of a local docs build:

(ipython-dev) docs$ make html
python3 autogen_shortcuts.py
Created docs for shortcuts
mkdir -p build/html build/doctrees
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.6.3
Initializing GitHub plugin
loading pickled environment... not yet created
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://rpy2.readthedocs.io/en/version_2.8.x/objects.inv...
loading intersphinx inventory from https://traitlets.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://jupyter-client.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://ipyparallel.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory from https://jupyter.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://jedi.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://ipykernel.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://python-prompt-toolkit.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory from https://ipywidgets.readthedocs.io/en/stable/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 170 source files that are out of date
updating environment: 170 added, 0 changed, 0 removed
reading sources... [100%] whatsnew/version6                                                                                      
/home/doug/Documents/sprints/ipython/IPython/core/debugger.py:docstring of IPython.core.debugger.Pdb.do_q:3: WARNING: Unexpected indentation.
/home/doug/Documents/sprints/ipython/IPython/core/debugger.py:docstring of IPython.core.debugger.Pdb.do_quit:3: WARNING: Unexpected indentation.
/home/doug/Documents/sprints/ipython/docs/source/api/generated/IPython.core.interactiveshell.rst:66: WARNING: error while formatting arguments for IPython.core.interactiveshell.sphinxify: 'NoneType' object has no attribute '__mro__'
WARNING: /home/doug/Documents/sprints/ipython/IPython/utils/tokenize2.py:docstring of IPython.utils.tokenize2:15: (SEVERE/4) Missing matching underline for section title overline.

------------------------------------------------------------------------------
Tokenization help for Python programs.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] whatsnew/version6                                                                                       
WARNING: dot command 'dot' cannot be run (needed for graphviz output), check the graphviz_dot setting
/home/doug/Documents/sprints/ipython/IPython/testing/tools.py:docstring of IPython.testing.tools.ipexec:: WARNING: more than one target found for cross-reference 'stdout': IPython.testing.iptestcontroller.TestController.stdout, IPython.utils.capture.CapturedIO.stdout
generating indices... genindex py-modindex
writing additional pages... interactive/htmlnotebook interactive/notebook interactive/nbconvert interactive/public_server search
copying images... [100%] whatsnew/../_images/jedi_type_inference_60.png                                                          
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 6 warnings.

Build finished. The HTML pages are in build/html.

jzf2101 · 2017-11-20T18:09:19Z

My suspicion is that some of these issues come from https://github.com/ipython/ipython/blob/master/IPython/core/debugger.py#L312

jzf2101 · 2017-11-20T19:10:27Z

According to @syutbai this is a pdb issue

… error while formatting arguments for IPython.core.interactiveshell.sphinxify

jzf2101 · 2017-11-20T20:42:03Z

@takluyver @Carreau @minrk could we have a second review?

syutbai · 2017-11-20T20:49:55Z

Regarding warning message:

/data/apps/ipython/IPython/core/debugger.py:docstring of IPython.core.debugger.Pdb.do_q:3: WARNING: Unexpected indentation.
/data/apps/ipython/IPython/core/debugger.py:docstring of IPython.core.debugger.Pdb.do_quit:3: WARNING: Unexpected indentation.

Root cause:
Wrapping docstring from PDB that contains a '\n', Sphinx complains about indentation when it processes the '\n'.

Making changes in PDB:

PDB has Docstring formatting that drives help file formatting.
Docstring triggering the message below contains a '\n': Q(uit)\nexit . Pdb functions do_quit() and do_exit() is aliased so the resulting help file for this formats the "exit" word elegantly beneath the "Quit".
Making changes in PDB by removing the '\n' uglifies the Docstring, where the word "exit" starts on column 1.

Making changes in IPython debugger.py:

Escaping logic can be added to the docstring wrapping function to handle '\n'. This will likely make the code ugly.

Making changes in Sphinx:

Where "WARNING: Unexpected Indentation" is thrown, handle docstrings with '\n'. Code needs to be investigated in more details.

Carreau · 2017-11-21T09:21:39Z

I think these two warnings messages are ok for now. Another possibility is to see how to ignore some warnings in sphinx. There might be a way to ignore warnings base on RegEx but this can be in a second PR. Appologies if you've spent a long time looking into this. I wouldn't bother trying to patch CPython itself I think the issue was already raise and the answer was "Won't fix".

I'll review the code now ! Thanks for sprinting on this, extra kudos for tackling documentation !

re-enable 3.3 and only exclude docs on 3.3

Carreau · 2017-11-21T09:30:52Z

I've re-enabled 3.3 (we definitively want to test the IPython code on 3.3. I think it is ok to build the docs only on the latest Python so at some point we might be able to simplify the matrix/exclude section into simply an - include section .

jzf2101 · 2017-11-21T12:44:43Z

@Carreau the tests appear to pass, do you have other comments in your review before we pull?

takluyver · 2017-11-21T13:39:09Z

I think something's gone wrong with the Travis config - Matthias' change hasn't restored Python 3.3. I'm going to have a look now.

takluyver · 2017-11-21T13:51:02Z

OK, docs now only build on Python 3.6.

olesyabar added 3 commits November 20, 2017 11:10

Changing files per example in Jupyter repo

77d326e

Fixing typo in path

df83168

Dropping Python 3.3 due to Travis issues + adding 'group' back

17c2cea

douglatornell mentioned this pull request Nov 20, 2017

Add docs about building the docs. #10912

Merged

jzf2101 mentioned this pull request Nov 20, 2017

Drop support for Python 3.3 #10833

Merged

olesyabar added 2 commits November 20, 2017 14:35

Removed extra dependencies

e7a62c4

Adding necessary module used for building docs to get rid of WARNING:…

326f41b

… error while formatting arguments for IPython.core.interactiveshell.sphinxify

syutbai mentioned this pull request Nov 20, 2017

Newline ('\n') in docstring drops words until end of line sphinx-doc/sphinx#4251

Closed

douglatornell mentioned this pull request Nov 20, 2017

Build Documentation in Travis #10895

Closed

re-enable 3.3

1a8329d

re-enable 3.3 and only exclude docs on 3.3

Carreau changed the title ~~Attempt to solve issue #10895~~ Attempt to build documentation with Travis-CI Nov 21, 2017

Test docs build only on Python 3.6

8b7e5ac

Carreau merged commit b73e418 into ipython:master Nov 21, 2017

Carreau added this to the 7.0 milestone Sep 6, 2018

Uh oh!

Attempt to build documentation with Travis-CI #10911

Attempt to build documentation with Travis-CI #10911

Uh oh!

Conversation

olesyabar commented Nov 20, 2017

Uh oh!

jzf2101 commented Nov 20, 2017

Uh oh!

jzf2101 commented Nov 20, 2017

Uh oh!

douglatornell commented Nov 20, 2017

Uh oh!

jzf2101 commented Nov 20, 2017

Uh oh!

jzf2101 commented Nov 20, 2017

Uh oh!

jzf2101 commented Nov 20, 2017

Uh oh!

syutbai commented Nov 20, 2017

Uh oh!

Carreau commented Nov 21, 2017

Uh oh!

Carreau commented Nov 21, 2017

Uh oh!

jzf2101 commented Nov 21, 2017

Uh oh!

takluyver commented Nov 21, 2017

Uh oh!

takluyver commented Nov 21, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants