Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

unable to build docs locally #2529

Closed
jseabold opened this issue Oct 18, 2013 · 16 comments
Closed

unable to build docs locally #2529

jseabold opened this issue Oct 18, 2013 · 16 comments
Milestone

Comments

@jseabold
Copy link
Contributor

Is this a local error? Was having the problem, so I updated to master and I still see it. haven't attempted to debug.

|18 $ python --version
Python 2.7.4
[~/src/matplotlib-skipper/doc] (master)
|19 $ git rev-parse HEAD
a3d2992e2af170313834f922f2212201e2c61a2a
[~/src/matplotlib-skipper/doc] (master)
|20 $ python make.py html
Running Sphinx v1.2b1
Initializing GitHub plugin
loading pickled environment... not yet created
[autosummary] generating autosummary for: api/afm_api.rst, api/animation_api.rst, api/api_changes.rst, api/artist_api.rst, api/axes_api.rst, api/axis_api.rst, api/backend_bases_api.rst, api/backend_gtkagg_api.rst, api/backend_pdf_api.rst, api/backend_qt4agg_api.rst, ..., users/pyplot_tutorial.rst, users/recipes.rst, users/screenshots.rst, users/shell.rst, users/text_intro.rst, users/text_props.rst, users/tight_layout_guide.rst, users/transforms_tutorial.rst, users/usetex.rst, users/whats_new.rst
Failed to import 'matplotlib.backends.backend_wxagg': no module named matplotlib.backends.backend_wxagg
animation, api, axes_grid, color, event_handling, images_contours_and_fields, lines_bars_and_markers, misc, mplot3d, old_animation, pie_and_polar_charts, pylab_examples, shapes_and_collections, showcase, specialty_plots, statistics, subplots_axes_and_figures, tests, text_labels_and_annotations, ticks_and_spines, units, user_interfaces, widgets, 
building [html]: targets for 591 source files that are out of date
updating environment: 591 added, 0 changed, 0 removed
reading sources... [  0%] api/artist_api                                         
Sphinx error:
'ascii' codec can't encode character u'\xe9' in position 168: ordinal not in range(128)
Building HTML failed.
@mdboom
Copy link
Member

mdboom commented Oct 18, 2013

I can't reproduce this myself, but I have Sphinx 1.2b3, not 1.2b1 (don't know if that makes a difference).

The docstring in question is most likely this one:

https://github.com/matplotlib/matplotlib/blob/master/lib/matplotlib/patches.py#L1285

But I'm not sure why it's failing for you and not me -- that's a Unicode string, and Sphinx should be generating everything in utf-8. If we could coax a traceback out of Sphinx to see where that encoding is happening, that might help.

@WeatherGod
Copy link
Member

This is the identical error I reported back during the release candidate
phase of v1.3. I never figured it out and I just resorted to building the
1.2.1 docs instead.

@mdboom
Copy link
Member

mdboom commented Oct 18, 2013

Can one of you apply this patch and see if that gives us a better traceback out of Sphinx?

diff --git a/doc/make.py b/doc/make.py
index ab48fef..7cda626 100755
--- a/doc/make.py
+++ b/doc/make.py
@@ -142,7 +142,7 @@ def html():
         options = "-D plot_formats=\"[('png', 80)]\""
     else:
         options = ''
-    if os.system('sphinx-build %s -b html -d build/doctrees . build/html' % options):
+    if os.system('sphinx-build %s -T -b html -d build/doctrees . build/html' % options):
         raise SystemExit("Building HTML failed.")

     figures_dest_path = 'build/html/pyplots'

@jankatins
Copy link
Contributor

This seems to be a windows vs linux problem: see pandas-dev/pandas#5245 for a similar error in pandas and windows

@WeatherGod
Copy link
Member

I am a Linux user... never tried building docs on Windows.

@jseabold
Copy link
Contributor Author

I was also on linux. I will try the patch on Monday when I'm back on my machine. I currently have intermittent internet access hence my need for local docs build.

@mdboom
Copy link
Member

mdboom commented Oct 19, 2013

If you want a local copy of the docs, you can also check out the
matplotlib.github.com repository.

Michael Droettboom
On Oct 19, 2013 7:12 AM, "Skipper Seabold" notifications@github.com wrote:

I was also on linux. I will try the patch on Monday when I'm back on my
machine. I currently have intermittent internet access hence my need for
local docs build.


Reply to this email directly or view it on GitHubhttps://github.com//issues/2529#issuecomment-26648142
.

@jseabold
Copy link
Contributor Author

The -T flag patch did not work for me. Likewise upgrading to Sphinx 1.2b3 did not work.

@jseabold
Copy link
Contributor Author

Maybe a more useful traceback from 1.2b3

reading sources... [  0%] api/artist_api                                         
Traceback (most recent call last):
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/cmdline.py", line 246, in main
    app.build(force_all, filenames)
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/application.py", line 212, in build
    self.builder.build_update()
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/builders/__init__.py", line 214, in build_update
    'out of date' % len(to_build))
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/builders/__init__.py", line 234, in build
    purple, length):
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/builders/__init__.py", line 134, in status_iterator
    for item in iterable:
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/environment.py", line 470, in update_generator
    self.read_doc(docname, app=app)
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/environment.py", line 621, in read_doc
    raise SphinxError(str(err))
SphinxError: 'ascii' codec can't encode character u'\xe9' in position 168: ordinal not in range(128)

Sphinx error:
'ascii' codec can't encode character u'\xe9' in position 168: ordinal not in range(128)
Building HTML failed.

@mdboom
Copy link
Member

mdboom commented Oct 21, 2013

When you say "-T" flag did not work, does that mean it did not give you an extended traceback? I was not expecting it to change behavior, only to provide a more detailed traceback. Perhaps that's what we're getting from 1.2b3 above, anyway. In any case, it's not very helpful -- the traceback leads us to a try/except that is hiding the source of the original traceback.

Around line 617 in sphinx/environment.py is the following:

        try:
            pub.publish()
            doctree = pub.document
        except UnicodeError, err:
            raise SphinxError(str(err))

Could you try replacing it with

        try:
            pub.publish()
            doctree = pub.document
        except UnicodeError, err:
            import traceback
            traceback.print_exc()
            raise SphinxError(str(err))

and sending me the output?

@jseabold
Copy link
Contributor Author

Ah, that's what the T does. I thought maybe it was an encoding thing and didn't check. Helpful to know. Looks like a problem with numpydoc.

Traceback (most recent call last):st_api                                         
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/environment.py", line 618, in read_doc
    pub.publish()
  File "/usr/local/lib/python2.7/dist-packages/docutils/core.py", line 217, in publish
    self.settings)
  File "/usr/local/lib/python2.7/dist-packages/docutils/readers/__init__.py", line 72, in read
    self.parse()
  File "/usr/local/lib/python2.7/dist-packages/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/__init__.py", line 172, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 174, in run                                                                  
    input_source=document['source'])                                             
  File "/usr/local/lib/python2.7/dist-packages/docutils/statemachine.py", line 239, in run                                                                        
    context, state, transitions)                                                 
  File "/usr/local/lib/python2.7/dist-packages/docutils/statemachine.py", line 460, in check_line                                                                 
    return method(match, context, next_state)                                    
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 2965, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 331, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 399, in new_subsection
    node=section_node, match_titles=True)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 286, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 199, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python2.7/dist-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/local/lib/python2.7/dist-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 2730, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 331, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 399, in new_subsection
    node=section_node, match_titles=True)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 286, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 199, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python2.7/dist-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/local/lib/python2.7/dist-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 2303, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 2315, in explicit_construct
    return method(self, expmatch)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 2058, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/local/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line 2107, in run_directive
    result = directive_instance.run()
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/ext/autodoc.py", line 1374, in run
    documenter.generate(more_content=self.content)
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/ext/autodoc.py", line 767, in generate
    self.document_members(all_members)
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/ext/autodoc.py", line 691, in document_members
    check_module=members_check_module and not isattr)
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/ext/autodoc.py", line 764, in generate
    self.add_content(more_content)
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/ext/autodoc.py", line 1095, in add_content
    ModuleLevelDocumenter.add_content(self, more_content)
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/ext/autodoc.py", line 501, in add_content
    for i, line in enumerate(self.process_doc(docstrings)):
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/ext/autodoc.py", line 465, in process_doc
    self.options, docstringlines)
  File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b3-py2.7.egg/sphinx/application.py", line 358, in emit
    results.append(callback(self, *args))
  File "/usr/local/lib/python2.7/dist-packages/numpydoc-0.5.dev-py2.7.egg/numpydoc/numpydoc.py", line 53, in mangle_docstrings
    doc = str(doc).decode('utf-8')
UnicodeEncodeError: 'ascii' codec can't encode character u'\xe9' in position 168: ordinal not in range(128)

Sphinx error:
'ascii' codec can't encode character u'\xe9' in position 168: ordinal not in range(128)
Building HTML failed.

@jseabold
Copy link
Contributor Author

Numpydoc version.

[~/src/numpydoc] (master)
|5 $ git rev-parse HEAD
06407d12fbf5f16dc79f53418210f69fc52b7649

@jseabold
Copy link
Contributor Author

Heh

numpy/numpydoc#1

@jseabold
Copy link
Contributor Author

@mdboom Your patch works for this problem, so feel free to close this as you see fit.

@mdboom
Copy link
Member

mdboom commented Oct 21, 2013

Heh. Sorry I didn't remember my own bug that I had reported. Obviously, I have the local patch, which is why it "Works for me[TM]". Anyway, thanks for reporting this and +1'ing the numpydoc bug.

I'm going to keep this open and NOTE TO SELF to harass (in a friendly way) the numpydoc folks to get this done before the next matplotlib release.

@tacaswell
Copy link
Member

Closing this because the patch has been merged into numpydoc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants