Fix Sphinx warnings and convert new ones into errors

dandi/dandiapi.py

@@ -526,16 +526,13 @@ def upload_raw_asset(
         this version of the Dandiset and return the resulting asset.  Blocks
         until the upload is complete.
 
-        Parameters
-        ----------
-        filepath: str or PathLike
-          the path to the local file to upload
-        asset_metadata: dict
-          Metadata for the uploaded asset file.  Must include a "path" field
-          giving the POSIX path at which the uploaded file will be placed on
-          the server.
-        jobs: int
-          Number of threads to use for uploading; defaults to 5
+        :param filepath: the path to the local file to upload
+        :type filepath: str or PathLike
+        :param dict asset_metadata:
+            Metadata for the uploaded asset file.  Must include a "path" field
+            giving the POSIX path at which the uploaded file will be placed on
+            the server.
+        :param int jobs: Number of threads to use for uploading; defaults to 5
         """
         for status in self.iter_upload_raw_asset(filepath, asset_metadata, jobs=jobs):
             if status["status"] == "done":
@@ -553,22 +550,19 @@ def iter_upload_raw_asset(
         this version of the Dandiset, returning a generator of status
         `dict`\\s.
 
-        Parameters
-        ----------
-        filepath: str or PathLike
-          the path to the local file to upload
-        asset_metadata: dict
-          Metadata for the uploaded asset file.  Must include a "path" field
-          giving the POSIX path at which the uploaded file will be placed on
-          the server.
-        jobs: int
-          Number of threads to use for uploading; defaults to 5
-
-        Returns
-        -------
-        A generator of `dict`\\s containing at least a ``"status"`` key.  Upon
-        successful upload, the last `dict` will have a status of ``"done"`` and
-        an ``"asset"`` key containing the resulting `RemoteAsset`.
+        :param filepath: the path to the local file to upload
+        :type filepath: str or PathLike
+        :param dict asset_metadata:
+            Metadata for the uploaded asset file.  Must include a "path" field
+            giving the POSIX path at which the uploaded file will be placed on
+            the server.
+        :param int jobs:
+            Number of threads to use for uploading; defaults to 5
+        :returns:
+            A generator of `dict`\\s containing at least a ``"status"`` key.
+            Upon successful upload, the last `dict` will have a status of
+            ``"done"`` and an ``"asset"`` key containing the resulting
+            `RemoteAsset`.
         """
         from .support.digests import get_dandietag
 

dandi/dandiarchive.py

@@ -206,15 +206,11 @@ def get_assets(self, client: DandiAPIClient) -> Iterator[RemoteAsset]:
 def navigate_url(url):
     """Context manager to 'navigate' URL pointing to DANDI archive.
 
-    Parameters
-    ----------
-    url: str
-      URL which might point to a dandiset, a folder, or an asset(s)
-
-    Yields
-    ------
-    client, dandiset, assets (generator)
-      `client` will have established a session for the duration of the context
+    :param str url: URL which might point to a dandiset, a folder, or an
+        asset(s)
+
+    :returns: Generator of one ``(client, dandiset, assets)``; ``client`` will
+        have established a session for the duration of the context
     """
     parsed_url = parse_dandi_url(url)
     with parsed_url.navigate() as (client, dandiset, assets):
@@ -337,27 +333,28 @@ class _dandi_url_parser:
 
     @classmethod
     def parse(cls, url, *, map_instance=True):
-        """Parse url like and return server (address), asset_id and/or directory
+        """
+        Parse url like and return server (address), asset_id and/or directory
 
         Example URLs (as of 20210428):
+
         - Dataset landing page metadata:
           https://gui.dandiarchive.org/#/dandiset/000003
 
         Individual and multiple files:
-          - dandi???
+
+        - dandi???
 
         Multiple selected files + folders -- we do not support ATM, then further
         RFing would be due, probably making this into a generator or returning a
         list of entries.
 
         "Features":
 
-        - uses some of `known_instance`s to map some urls, e.g. from
+        - uses some of `known_instances` to map some urls, e.g. from
           gui.dandiarchive.org ones into girder.
 
-        Returns
-        -------
-        ParsedDandiURL
+        :rtype: ParsedDandiURL
         """
         lgr.debug("Parsing url %s", url)
 

dandi/tests/skip.py

@@ -12,13 +12,13 @@
 
 There are two main ways to skip in pytest:
 
-  * decorating a test function, such as
+* decorating a test function, such as::
 
         @pytest.mark.skip(sys.platform.startswith("win"), reason="on windows")
         def test_func():
             [...]
 
-  * skipping inline, such as
+* skipping inline, such as::
 
         def test_func():
             if sys.platform.startswith("win"):
@@ -28,16 +28,16 @@ def test_func():
 This module provides a mechanism to register a reason and condition as both a
 decorator and an inline function:
 
-  * Within this module, create a condition function that returns a tuple of the
-    form (REASON, COND). REASON is a str that will be shown as the reason for
-    the skip, and COND is a boolean indicating if the test should be skipped.
+* Within this module, create a condition function that returns a tuple of the
+  form (REASON, COND). REASON is a str that will be shown as the reason for
+  the skip, and COND is a boolean indicating if the test should be skipped.
 
-    For example
+  For example::
 
     def windows():
         return "on windows", sys.platform.startswith("win")
 
-  * Then add the above function to CONDITION_FNS.
+* Then add the above function to CONDITION_FNS.
 
 Doing that will make the skip condition available in two places:
 `mark.skipif_NAME` and `skipif.NAME`. So, for the above example, there would

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build

docs/source/conf.py

@@ -53,4 +53,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]

tox.ini

@@ -24,7 +24,7 @@ commands =
 basepython = python3
 deps = -rdocs/requirements.txt
 changedir = docs
-commands = sphinx-build -E -b html source build
+commands = sphinx-build -E -W -b html source build
 
 [pytest]
 addopts = --tb=short --durations=10