Enable nitpicky Sphinx warnings, fix issues and have the documentation build fail

Author: Gallaecio

.travis.yml

@@ -22,6 +22,10 @@ matrix:
       env: TOXENV=py37
       dist: xenial
       sudo: true
+    - python: 3.7
+      env: TOXENV=docs
+      dist: xenial
+      sudo: true
 install:
   - |
       if [ "$TOXENV" = "pypy" ]; then

docs/conf.py

@@ -40,7 +40,11 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -273,3 +277,22 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+
+# -- Options for the InterSphinx extension ------------------------------------
+
+intersphinx_mapping = {
+    'cssselect': ('https://cssselect.readthedocs.io/en/latest', None),
+    'python': ('https://docs.python.org/3', None),
+}
+
+
+# --- Nitpicking options ------------------------------------------------------
+
+nitpicky = True
+nitpick_ignore = [
+    ('py:class', 'cssselect.xpath.GenericTranslator'),
+    ('py:class', 'cssselect.xpath.HTMLTranslator'),
+    ('py:class', 'cssselect.xpath.XPathExpr'),
+    ('py:class', 'lxml.etree.XMLParser'),
+]

docs/index.rst

@@ -15,6 +15,7 @@ Contents:
 
    installation
    usage
+   parsel
    history
 
 Indices and tables

docs/modules.rst

@@ -1,38 +1,30 @@
-parsel package
-==============
+API reference
+=============
 
-Submodules
-----------
-
-parsel.csstranslator module
----------------------------
+parsel.csstranslator
+--------------------
 
 .. automodule:: parsel.csstranslator
     :members:
     :undoc-members:
     :show-inheritance:
 
-parsel.selector module
-----------------------
 
-.. automodule:: parsel.selector
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. _topics-selectors-ref:
 
-parsel.utils module
--------------------
+parsel.selector
+---------------
 
-.. automodule:: parsel.utils
+.. automodule:: parsel.selector
     :members:
     :undoc-members:
     :show-inheritance:
 
 
-Module contents
----------------
+parsel.utils
+------------
 
-.. automodule:: parsel
+.. automodule:: parsel.utils
     :members:
     :undoc-members:
     :show-inheritance:

docs/parsel.rst

@@ -857,27 +857,11 @@ There are third-party tools that allow using Parsel from the command line:
 .. _cURL: https://curl.haxx.se/
 
 
-.. _topics-selectors-ref:
-
-API reference
-=============
-
-Selector objects
-----------------
-
-.. autoclass:: parsel.selector.Selector
-    :members:
-
-
-SelectorList objects
---------------------
-
-.. autoclass:: parsel.selector.SelectorList
-    :members:
-
-
 .. _selector-examples-html:
 
+Examples
+========
+
 Working on HTML
 ---------------
 
@@ -936,7 +920,8 @@ Removing namespaces
 When dealing with scraping projects, it is often quite convenient to get rid of
 namespaces altogether and just work with element names, to write more
 simple/convenient XPaths. You can use the
-:meth:`Selector.remove_namespaces` method for that.
+:meth:`Selector.remove_namespaces <parsel.selector.Selector.remove_namespaces>`
+method for that.
 
 Let's show an example that illustrates this with the Python Insider blog atom feed.
 
@@ -947,10 +932,12 @@ Let's download the atom feed using `requests`_ and create a selector::
     >>> text = requests.get('https://feeds.feedburner.com/PythonInsider').text
     >>> sel = Selector(text=text, type='xml')
 
-This is how the file starts::
+This is how the file starts:
+
+.. code-block:: xml
 
     <?xml version="1.0" encoding="UTF-8"?>
-    <?xml-stylesheet ...
+    <?xml-stylesheet ... ?>
     <feed xmlns="http://www.w3.org/2005/Atom"
           xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
           xmlns:blogger="http://schemas.google.com/blogger/2008"
@@ -959,6 +946,7 @@ This is how the file starts::
           xmlns:thr="http://purl.org/syndication/thread/1.0"
           xmlns:feedburner="http://rssnamespace.org/feedburner/ext/1.0">
       ...
+    </feed>
 
 You can see several namespace declarations including a default
 "http://www.w3.org/2005/Atom" and another one using the "gd:" prefix for
@@ -970,8 +958,9 @@ We can try selecting all ``<link>`` objects and then see that it doesn't work
     >>> sel.xpath("//link")
     []
 
-But once we call the :meth:`Selector.remove_namespaces` method, all
-nodes can be accessed directly by their names::
+But once we call the :meth:`Selector.remove_namespaces
+<parsel.selector.Selector.remove_namespaces>` method, all nodes can be accessed
+directly by their names::
 
     >>> sel.remove_namespaces()
     >>> sel.xpath("//link")

docs/readme.rst

@@ -6,3 +6,15 @@ deps =
     -r{toxinidir}/tests/requirements.txt
 
 commands = py.test --cov=parsel --cov-report= {posargs:parsel tests}
+
+[docs]
+changedir = docs
+deps =
+    sphinx
+    sphinx_rtd_theme
+
+[testenv:docs]
+changedir = {[docs]changedir}
+deps = {[docs]deps}
+commands =
+    sphinx-build -W -b html . {envtmpdir}/html