Docs: fix broken internal refs, fix broken intersphinx cross-refs to multidict, minor styling fixes (#665)

Author: hoefling

.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+
+python:
+   install:
+   - requirements: requirements/doc.txt
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: true

CHANGES/665.doc.1

@@ -0,0 +1 @@
+Fixed broken internal references to :meth:`~URL.human_repr`.

CHANGES/665.doc.2

@@ -0,0 +1 @@
+Fixed broken external references to :doc:`multidict:index` docs.

Makefile

@@ -53,13 +53,13 @@ cov: lint .develop
 
 
 doc: doctest doc-spelling
-	make -C docs html SPHINXOPTS="-W -E"
+	make -C docs html SPHINXOPTS="-W -E --keep-going -n"
 	@echo "open file://`pwd`/docs/_build/html/index.html"
 
 
 doctest: .develop
-	make -C docs doctest SPHINXOPTS="-W -E"
+	make -C docs doctest SPHINXOPTS="-W -E --keep-going -n"
 
 
 doc-spelling:
-	make -C docs spelling SPHINXOPTS="-W -E"
+	make -C docs spelling SPHINXOPTS="-W -E --keep-going -n"

docs/api.rst

@@ -7,7 +7,7 @@ Public API
 .. currentmodule:: yarl
 
 
-The only public *yarl* class is ``URL``:
+The only public *yarl* class is :class:`URL`:
 
 .. doctest::
 
@@ -66,7 +66,7 @@ Already encoded URL is not changed:
    >>> URL('http://xn--jxagkqfkduily1i.eu')
    URL('http://xn--jxagkqfkduily1i.eu')
 
-Use :meth:`URL.human_repr` for getting human readable representation:
+Use :meth:`~URL.human_repr` for getting human readable representation:
 
 .. doctest::
 
@@ -101,7 +101,7 @@ There are two kinds of properties: *decoded* and *encoded* (with
 .. attribute:: URL.scheme
 
    Scheme for absolute URLs, empty string for relative URLs or URLs
-   starting with `'//'` (:ref:`yarl-api-relative-urls`).
+   starting with ``'//'`` (:ref:`yarl-api-relative-urls`).
 
    .. doctest::
 
@@ -431,7 +431,7 @@ Absolute URL should start from either *scheme* or ``'//'``.
     A check for absolute URLs.
 
     Return ``True`` for absolute ones (having *scheme* or starting
-    with ``//``), ``False`` otherwise.
+    with ``'//'``), ``False`` otherwise.
 
    .. doctest::
 
@@ -449,11 +449,12 @@ New URL generation
 ------------------
 
 URL is an immutable object, every operation described in the
-section generates a new *URL* instance.
+section generates a new :class:`URL` instance.
 
 .. method:: URL.build(*, scheme=..., authority=..., user=..., password=..., \
-                      host=..., port=..., path=..., query=.., \
+                      host=..., port=..., path=..., query=..., \
                       query_string=..., fragment=..., encoded=False)
+   :classmethod:
 
    Creates and returns a new URL:
 
@@ -616,7 +617,7 @@ section generates a new *URL* instance.
    completely.
 
 
-   Returned ``URL`` object will contain query string which updated
+   Returned :class:`URL` object will contain query string which updated
    parts from passed query parts (or parts of parsed query string).
 
    Accepts any :class:`~collections.abc.Mapping` (e.g. :class:`dict`,
@@ -791,7 +792,7 @@ All URL data is stored in encoded form internally. It's pretty good
 for passing ``str(url)`` everywhere URL string is accepted but quite
 bad for memorizing by humans.
 
-.. method:: human_repr()
+.. method:: URL.human_repr()
 
    Return decoded human readable string for URL representation.
 

docs/conf.py

@@ -67,8 +67,8 @@
     pass
 
 intersphinx_mapping = {
-    "python": ("http://docs.python.org/3", None),
-    "multidict": ("http://multidict.readthedocs.io/", None),
+    "python": ("https://docs.python.org/3", None),
+    "multidict": ("https://multidict.readthedocs.io/en/stable", None),
 }
 
 
@@ -403,6 +403,5 @@
 #
 # texinfo_no_detailmenu = False
 
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+default_role = "any"
+nitpicky = True

docs/index.rst

@@ -76,7 +76,7 @@ getting *encoded* strings:
    >>> url.raw_path
    '/%D0%BF%D1%83%D1%82%D1%8C'
 
-Human readable representation of URL is available as :meth:`~yarl.URL.human_repr()`:
+Human readable representation of URL is available as :meth:`~yarl.URL.human_repr`:
 
 .. doctest::
 
@@ -101,7 +101,7 @@ manylinux-compliant because of the missing glibc and therefore, cannot be
 used with our wheels) the the tarball will be used to compile the library from
 the source code. It requires a C compiler and and Python headers installed.
 
-To skip the compilation you must explicitly opt-in by setting the `YARL_NO_EXTENSIONS`
+To skip the compilation you must explicitly opt-in by setting the ``YARL_NO_EXTENSIONS``
 environment variable to a non-empty value, e.g.:
 
 ::
@@ -115,7 +115,7 @@ by this variable.
 Dependencies
 ------------
 
-YARL requires :mod:`multidict` library.
+``yarl`` requires :mod:`multidict` library.
 
 It installs it automatically.