Docs: fix broken internal refs, fix broken intersphinx cross-refs to multidict, minor styling fixes

CHANGES/665.doc

@@ -0,0 +1,3 @@
+Fixed broken internal references to :meth:`~URL.human_repr()`.
+Fixed broken external references to :doc:`multidict:index` docs.
+Minor styling improvements.

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),
 }
 
 
@@ -402,7 +402,3 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #
 # texinfo_no_detailmenu = False
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}

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::