Skip to content

Attempt to build documentation with Travis-CI#10911

Merged
Carreau merged 7 commits intoipython:masterfrom
olesyabar:master
Nov 21, 2017
Merged

Attempt to build documentation with Travis-CI#10911
Carreau merged 7 commits intoipython:masterfrom
olesyabar:master

Conversation

@olesyabar
Copy link
Copy Markdown
Contributor

@olesyabar olesyabar commented Nov 20, 2017

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
Copy link
Copy Markdown
Contributor

jzf2101 commented Nov 20, 2017

@douglatornell can you confirm you also have these error?

@jzf2101
Copy link
Copy Markdown
Contributor

jzf2101 commented Nov 20, 2017

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

@douglatornell douglatornell mentioned this pull request Nov 20, 2017
Merged
@douglatornell
Copy link
Copy Markdown
Contributor

douglatornell commented Nov 20, 2017

@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 jzf2101 mentioned this pull request Nov 20, 2017
Merged
@jzf2101
Copy link
Copy Markdown
Contributor

jzf2101 commented Nov 20, 2017

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

@jzf2101
Copy link
Copy Markdown
Contributor

jzf2101 commented Nov 20, 2017

According to @syutbai this is a pdb issue

@olesyabar
Removed extra dependencies
e7a62c4
@olesyabar
Adding necessary module used for building docs to get rid of WARNING:…
326f41b 
… error while formatting arguments for IPython.core.interactiveshell.sphinxify
@jzf2101
Copy link
Copy Markdown
Contributor

jzf2101 commented Nov 20, 2017

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

@syutbai
Copy link
Copy Markdown

syutbai commented Nov 20, 2017

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.

@syutbai syutbai mentioned this pull request Nov 20, 2017
Closed
@douglatornell douglatornell mentioned this pull request Nov 20, 2017
Closed
@Carreau
Copy link
Copy Markdown
Member

Carreau commented Nov 21, 2017

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 !

@Carreau
re-enable 3.3
1a8329d 
re-enable 3.3 and only exclude docs on 3.3
@Carreau
Copy link
Copy Markdown
Member

Carreau commented Nov 21, 2017

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 .

@Carreau Carreau changed the title Attempt to solve issue #10895 Attempt to build documentation with Travis-CI Nov 21, 2017
@jzf2101
Copy link
Copy Markdown
Contributor

jzf2101 commented Nov 21, 2017

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

@takluyver
Copy link
Copy Markdown
Member

takluyver commented Nov 21, 2017

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
Copy link
Copy Markdown
Member

takluyver commented Nov 21, 2017

OK, docs now only build on Python 3.6.

@Carreau Carreau merged commit b73e418 into ipython:master Nov 21, 2017
@Carreau Carreau added this to the 7.0 milestone Sep 6, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

7.0

Development

Successfully merging this pull request may close these issues.

6 participants

@olesyabar @jzf2101 @douglatornell @syutbai @Carreau @takluyver