Use read the docs v2 config (fsspec#697)

* Use read the docs v2 config

* Fix sphinx build errors

* Pin docutils to render bullets in changelog correctly

* Fix display of colons in function arguments [skip ci]

* Temporarily allow doc build warnings

* Switch from numpydoc to napoleon

Author: ianthomas23

.readthedocs.yaml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: miniconda3-4.7
+
+conda:
+  environment: docs/environment.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true

docs/environment.yml

@@ -0,0 +1,9 @@
+name: s3fs
+channels:
+  - defaults
+dependencies:
+  - python= 3.9
+  - botocore
+  - docutils<0.17
+  - sphinx
+  - sphinx_rtd_theme

docs/requirements.txt

@@ -0,0 +1,5 @@
+.classifier:before {
+    font-style: normal;
+    margin: 0.5em;
+    content: ":";
+}

docs/source/_static/custom.css

@@ -41,9 +41,11 @@ API
 
 .. autoclass:: S3FileSystem
    :members:
+   :inherited-members:
 
 .. autoclass:: S3File
    :members:
+   :inherited-members:
 
 .. currentmodule:: s3fs.mapping
 

docs/source/api.rst

@@ -183,7 +183,7 @@ Version 0.4.0
 - Miscellaneous doc updates (:pr:`252`) by `James Bourbeau`_
 - Support for Python 3.8 (:pr:`264`) by `Tom Augspurger`_
 - Improved performance for ``isdir`` (:pr:`259`) by `Nate Yoder`_
-* Increased the minimum required version of fsspec to 0.6.0
+- Increased the minimum required version of fsspec to 0.6.0
 
 .. _`Martin Durant`: https://github.com/martindurant
 .. _`Marius van Niekerk`: https://github.com/mariusvniekerk

docs/source/changelog.rst

@@ -13,7 +13,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -36,7 +35,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.autosummary',
     'sphinx.ext.extlinks',
-    'numpydoc',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -68,13 +67,6 @@
 # The full version, including alpha/beta/rc tags.
 release = version
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
@@ -113,20 +105,13 @@
 todo_include_todos = False
 
 extlinks = {
-    "pr": ("https://github.com/fsspec/s3fs/pull/%s", "PR #"),
+    "pr": ("https://github.com/fsspec/s3fs/pull/%s", "PR #%s"),
 }
 
 
 # -- Options for HTML output ----------------------------------------------
 
-# Taken from docs.readthedocs.io:
-# on_rtd is whether we are on readthedocs.io
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -157,6 +142,10 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# Custom CSS file to override read the docs default CSS.
+# Contains workaround for issue #790.
+html_css_files = ["custom.css"]
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
@@ -278,6 +267,7 @@
 #man_show_urls = False
 
 
+
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples

docs/source/conf.py

@@ -333,6 +333,7 @@ Contents
 
 .. toctree::
    install
+   development
    api
    changelog
    :maxdepth: 2

docs/source/index.rst

@@ -1501,9 +1501,7 @@ async def _setxattr(self, path, copy_kwargs=None, **kw_args):
         >>> mys3file.setxattr(copy_kwargs={'ContentType': 'application/pdf'},
         ...     attribute_1='value1')  # doctest: +SKIP
 
-
-        .. Metadata Reference:
-        http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#object-metadata
+        .. _Metadata Reference: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#object-metadata
         """
 
         kw_args = {k.replace("_", "-"): v for k, v in kw_args.items()}