Fix doc warnings.

Review Request #73 — Created March 7, 2014 and submitted

travis
commons
pants-reviews
lahosken
Fix Sphinx documentation warnings.

Sphinx has a mode to treat warnings as fatal which will help us find+fix these very quickly:

    make SPHINXOPTS='-W' clean html

However, I could not find a way to disable "nonlocal image URI found" warnings, which are triggered as we show the current build status on the site (which is really nice). If someone figures out how to disable that warning I'm happy to always generate the site in strict mode, but for now AFAICT we can't use that option.
****************
WITH THIS CHANGE
****************

[tw-mbp13-travis commons]$ rm pants.pex; ./pants.bootstrap goal builddict && cd src/python/twitter/pants/docs/ && ./gen.py && make clean html && cd -
Build operating on targets: OrderedSet([PythonBinary(src/python/twitter/pants/bin/BUILD:pants)])
Building PythonBinary PythonBinary(src/python/twitter/pants/bin/BUILD:pants):
WARNING: Target has multiple python_binary targets!
Wrote /Users/travis/src/commons/dist/pants.pex

08:58:11 00:00 [main]
               (To run a reporting server: ./pants server)
08:58:11 00:00   [setup]
08:58:11 00:00     [bootstrap]
08:58:11 00:00     [parse]
08:58:11 00:00   [builddict]
08:58:11 00:00     [builddict]
                   Generating /Users/travis/src/commons/dist/builddict/goals_reference.rst
                   Generating /Users/travis/src/commons/dist/builddict/build_dictionary.rst
               SUCCESS
rm -rf _build/*
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.2.1
loading pickled environment... not yet created
building [html]: targets for 30 source files that are out of date
updating environment: 30 added, 0 changed, 0 removed
reading sources... [100%] tasks                                                                                                                                                                                 
/Users/travis/src/commons/src/python/twitter/pants/docs/howto_contribute.rst:5: WARNING: nonlocal image URI found: https://travis-ci.org/twitter/commons.png?branch=master
/Users/travis/src/commons/src/python/twitter/pants/docs/howto_contribute.rst:13: WARNING: nonlocal image URI found: https://travis-ci.org/twitter/commons.png?branch=master
/Users/travis/src/commons/src/python/twitter/pants/docs/howto_develop.rst:71: WARNING: nonlocal image URI found: https://travis-ci.org/twitter/commons.png?branch=master
/Users/travis/src/commons/src/python/twitter/pants/docs/howto_develop.rst:78: WARNING: nonlocal image URI found: https://travis-ci.org/twitter/commons.png?branch=master
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tasks                                                                                                                                                                                  
writing additional files... (83 module code pages) _modules/index genindex py-modindex search
copying images... [100%] images/intellij-project-structure-project.png                                                                                                                                          
copying static files... WARNING: html_static_path entry u'/Users/travis/src/commons/src/python/twitter/pants/docs/_static' does not exist
done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 5 warnings.

Build finished. The HTML pages are in _build/html.
/Users/travis/src/commons
[tw-mbp13-travis commons]$ 



**************
CURRENT OUTPUT
**************

[tw-mbp13-travis commons]$ rm pants.pex; ./pants.bootstrap goal builddict && cd src/python/twitter/pants/docs/ && ./gen.py && make clean html && cd -
Build operating on targets: OrderedSet([PythonBinary(src/python/twitter/pants/bin/BUILD:pants)])
Building PythonBinary PythonBinary(src/python/twitter/pants/bin/BUILD:pants):
WARNING: Target has multiple python_binary targets!
Wrote /Users/travis/src/commons/dist/pants.pex

08:59:03 00:00 [main]
               (To run a reporting server: ./pants server)
08:59:03 00:00   [setup]
08:59:03 00:00     [bootstrap]
08:59:03 00:00     [parse]
08:59:03 00:00   [builddict]
08:59:03 00:00     [builddict]
                   Generating /Users/travis/src/commons/dist/builddict/goals_reference.rst
                   Generating /Users/travis/src/commons/dist/builddict/build_dictionary.rst
               SUCCESS
rm -rf _build/*
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.2.1
loading pickled environment... not yet created
building [html]: targets for 30 source files that are out of date
updating environment: 30 added, 0 changed, 0 removed
reading sources... [100%] tasks                                                                                                                                                                                 
/Users/travis/src/commons/src/python/twitter/pants/docs/3rdparty_jvm.rst:29: WARNING: Include file u'/Users/travis/src/commons/3rdparty/jvm/com/sun/jersey/BUILD' not found or reading it failed
/Users/travis/src/commons/src/python/twitter/pants/docs/JVMProjects.rst:126: WARNING: Include file u'/Users/travis/src/commons/3rdparty/jvm/com/sun/jersey/BUILD' not found or reading it failed
/Users/travis/src/commons/src/python/twitter/pants/base/abbreviate_target_ids.py:docstring of twitter.pants.base.abbreviate_target_ids.abbreviate_target_ids:13: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/base/abbreviate_target_ids.py:docstring of twitter.pants.base.abbreviate_target_ids.abbreviate_target_ids:19: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/base/mustache.py:docstring of twitter.pants.base.mustache.MustacheRenderer:6: ERROR: Unexpected indentation.
/Users/travis/src/commons/src/python/twitter/pants/base/mustache.py:docstring of twitter.pants.base.mustache.MustacheRenderer:7: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/base/rcfile.py:docstring of twitter.pants.base.rcfile.RcFile:9: ERROR: Unexpected indentation.
/Users/travis/src/commons/src/python/twitter/pants/base/rcfile.py:docstring of twitter.pants.base.rcfile.RcFile:10: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/base/rcfile.py:docstring of twitter.pants.base.rcfile.RcFile.apply_defaults:8: ERROR: Unexpected indentation.
/Users/travis/src/commons/src/python/twitter/pants/base/rcfile.py:docstring of twitter.pants.base.rcfile.RcFile.apply_defaults:9: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/docs/build_dictionary.rst:393: ERROR: Unexpected indentation.
/Users/travis/src/commons/src/python/twitter/pants/docs/build_dictionary.rst:394: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/docs/howto_contribute.rst:5: WARNING: nonlocal image URI found: https://travis-ci.org/twitter/commons.png?branch=master
/Users/travis/src/commons/src/python/twitter/pants/docs/howto_contribute.rst:13: WARNING: nonlocal image URI found: https://travis-ci.org/twitter/commons.png?branch=master
/Users/travis/src/commons/src/python/twitter/pants/docs/howto_develop.rst:71: WARNING: nonlocal image URI found: https://travis-ci.org/twitter/commons.png?branch=master
/Users/travis/src/commons/src/python/twitter/pants/docs/howto_develop.rst:78: WARNING: nonlocal image URI found: https://travis-ci.org/twitter/commons.png?branch=master
/Users/travis/src/commons/src/python/twitter/pants/docs/index.rst:47: WARNING: toctree contains reference to nonexisting document u'README'
/Users/travis/src/commons/src/python/twitter/pants/targets/pants_target.py:docstring of twitter.pants.targets.pants_target.Pants:7: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/targets/python_artifact.py:docstring of twitter.pants.targets.python_artifact.PythonArtifact.with_binaries:8: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/tasks/args_resource_mapper.py:docstring of twitter.pants.tasks.args_resource_mapper.ArgsResourceMapper:8: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/travis/src/commons/src/python/twitter/pants/tasks/check_exclusives.py:docstring of twitter.pants.tasks.check_exclusives.CheckExclusives:20: WARNING: Definition list ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tasks                                                                                                                                                                                  
/Users/travis/src/commons/src/python/twitter/pants/docs/internals.rst:9: WARNING: unknown document: README
/Users/travis/src/commons/src/python/twitter/pants/docs/python-readme.rst:61: WARNING: unknown document: README
/Users/travis/src/commons/src/python/twitter/pants/docs/setup_repo.rst:5: WARNING: unknown document: README
writing additional files... (83 module code pages)
TR
  1. Just a sec... this diff didn't post correctly.
    
    I added another remote to my git working directory and think that messed stuff up :/
  2. 
      
TR
TR
LA
  1. Thank you for doing this.
    
    I'm gonna try tinkering with our layout.html. If I can get it to show our travis-ci-icon dealie, then we can move that icon out of our ReST, say bye-bye to those warnings and yay.
  2. 
      
TR
Review request changed

Status: Closed (submitted)

Loading...