From b1079ab66e92bc584fff1d2f554ca18c2c1276e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oleg=20H=C3=B6fling?= Date: Sun, 23 Jan 2022 13:56:34 +0100 Subject: [PATCH] Docs: fix broken internal refs, fix broken intersphinx cross-refs to multidict, minor styling fixes (#665) --- .readthedocs.yaml | 10 ++++++++++ CHANGES/665.doc.1 | 1 + CHANGES/665.doc.2 | 1 + Makefile | 6 +++--- docs/api.rst | 17 +++++++++-------- docs/conf.py | 9 ++++----- docs/index.rst | 6 +++--- 7 files changed, 31 insertions(+), 19 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 CHANGES/665.doc.1 create mode 100644 CHANGES/665.doc.2 diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..2b4cb977 --- /dev/null +++ b/.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 diff --git a/CHANGES/665.doc.1 b/CHANGES/665.doc.1 new file mode 100644 index 00000000..c9f9bde6 --- /dev/null +++ b/CHANGES/665.doc.1 @@ -0,0 +1 @@ +Fixed broken internal references to :meth:`~URL.human_repr`. diff --git a/CHANGES/665.doc.2 b/CHANGES/665.doc.2 new file mode 100644 index 00000000..41486577 --- /dev/null +++ b/CHANGES/665.doc.2 @@ -0,0 +1 @@ +Fixed broken external references to :doc:`multidict:index` docs. diff --git a/Makefile b/Makefile index ab4a6715..e0e0c788 100644 --- a/Makefile +++ b/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" diff --git a/docs/api.rst b/docs/api.rst index 0308c4fb..aba8f2ea 100644 --- a/docs/api.rst +++ b/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. diff --git a/docs/conf.py b/docs/conf.py index e23d9a9c..43d0ed50 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index 288289a9..637acfa1 100644 --- a/docs/index.rst +++ b/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.