Skip to content

Commit 3f7df7f

Browse files
Fix all sphinx warnings (#1106)
* Fix warnings on 'make html' * Fix warnings on 'sphinx-build' Co-authored-by: Martin Durant <[email protected]>
1 parent b46862a commit 3f7df7f

19 files changed

Lines changed: 52 additions & 39 deletions

‎docs/source/api.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ Built-in Implementations
130130
fsspec.implementations.dbfs.DatabricksFileSystem
131131
fsspec.implementations.reference.ReferenceFileSystem
132132
fsspec.implementations.dirfs.DirFileSystem
133+
fsspec.implementations.tar.TarFileSystem
133134

134135
.. autoclass:: fsspec.implementations.ftp.FTPFileSystem
135136
:members: __init__
@@ -194,6 +195,9 @@ Built-in Implementations
194195
.. autoclass:: fsspec.implementations.dirfs.DirFileSystem
195196
:members: __init__
196197

198+
.. autoclass:: fsspec.implementations.tar.TarFileSystem
199+
:members: __init__
200+
197201
Other Known Implementations
198202
---------------------------
199203

@@ -244,3 +248,12 @@ Read Buffering
244248

245249
.. autoclass:: fsspec.caching.BlockCache
246250
:members:
251+
252+
Utilities
253+
---------
254+
255+
.. autosummary::
256+
257+
fsspec.utils.read_block
258+
259+
.. autofunction:: fsspec.utils.read_block

‎docs/source/changelog.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@ Other
218218

219219
Fixes
220220

221-
- Removed inaccurate `ZipFileSystem.cat()` override so that the base
221+
- Removed inaccurate ``ZipFileSystem.cat()`` override so that the base
222222
class' version is used (#789)
223223
- fix entrypoint processing (#784)
224224
- case where no blocks of a block-cache have yet been loaded (#801)
@@ -475,7 +475,7 @@ Version 0.8.3
475475
Features:
476476

477477
- error options for cat
478-
- memory fs created time in detailed `ls`
478+
- memory fs created time in detailed ``ls```
479479

480480

481481
Fixes:
@@ -604,7 +604,7 @@ Version 0.6.0
604604
file reads in blocks (:pr:`191`).
605605
* Fixed equality checks for file system instance to return ``False`` when compared to objects
606606
other than file systems (:pr:`192`)
607-
* Fixed a bug in :meth:`fsspec.FSMap.keys` returning a generator, which was consumed upon iteration (:pr:`189`).
607+
* Fixed a bug in ``fsspec.FSMap.keys`` returning a generator, which was consumed upon iteration (:pr:`189`).
608608
* Removed the magic addition of aliases in ``AbstractFileSystem.__init__``. Now alias methods are always
609609
present (:pr:`177`)
610610
* Deprecated passing ``trim`` to :class:`fsspec.spec.AbstractBufferedFile`. Pass it in ``storage_options`` instead (:pr:`188`)

‎docs/source/conf.py‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -70,13 +70,6 @@
7070
# The full version, including alpha/beta/rc tags.
7171
release = fsspec.__version__
7272

73-
# The language for content autogenerated by Sphinx. Refer to documentation
74-
# for a list of supported languages.
75-
#
76-
# This is also used if you do content translation via gettext catalogs.
77-
# Usually you set "language" from the command line for these cases.
78-
language = None
79-
8073
# List of patterns, relative to source directory, that match files and
8174
# directories to ignore when looking for source files.
8275
# This patterns also effect to html_static_path and html_extra_path
@@ -192,6 +185,6 @@
192185
]
193186

194187
extlinks = {
195-
"issue": ("https://github.com/fsspec/filesystem_spec/issues/%s", "GH#"),
196-
"pr": ("https://github.com/fsspec/filesystem_spec/pull/%s", "GH#"),
188+
"issue": ("https://github.com/fsspec/filesystem_spec/issues/%s", "GH#%s"),
189+
"pr": ("https://github.com/fsspec/filesystem_spec/pull/%s", "GH#%s"),
197190
}

‎docs/source/features.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@ option exists to copy files locally when you first access them, and thereafter t
252252
This local cache of data might be temporary (i.e., attached to the process and discarded when the
253253
process ends) or at some specific location in your local storage.
254254

255-
Two mechanisms are provided, and both involve wrapping a `target` filesystem. The following example
255+
Two mechanisms are provided, and both involve wrapping a ``target`` filesystem. The following example
256256
creates a file-based cache.
257257

258258
.. code-block:: python

‎docs/source/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ The following libraries use ``fsspec`` internally for path and file handling:
7272
Installation
7373
------------
7474

75-
`fsspec` can be installed from PyPI or conda and has no dependencies of its own
75+
``fsspec`` can be installed from PyPI or conda and has no dependencies of its own
7676

7777
.. code-block:: sh
7878
@@ -88,7 +88,7 @@ pip install syntax below, or install the specific package required
8888
pip install fsspec[gcs]
8989
conda install -c conda-forge gcsfs
9090
91-
`fsspec` attempts to provide the right message when you attempt to use a filesystem
91+
``fsspec``` attempts to provide the right message when you attempt to use a filesystem
9292
for which you need additional dependencies.
9393
The current list of known implementations can be found as follows
9494

‎docs/source/intro.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ At the same time, the Apache `Arrow`_ project was also concerned with a similar
3333
particularly a common interface to local and HDFS files, for example the
3434
`hdfs`_ interface (which actually communicated with HDFS
3535
with a choice of driver). These are mostly used internally within Arrow, but Dask was modified in order to be able
36-
to use the alternate HDFS interface (which solves some security issues with `hdfs3`). In the process, a
36+
to use the alternate HDFS interface (which solves some security issues with ``hdfs3``). In the process, a
3737
`conversation`_
3838
was started, and I invite all interested parties to continue the conversation in this location.
3939

@@ -51,7 +51,7 @@ Influences
5151
The following places to consider, when choosing the definitions of how we would like the file-system specification
5252
to look:
5353

54-
#. python's `os`_ module and its `path` namespace; also other file-connected
54+
#. python's `os`_ module and its `path`_ namespace; also other file-connected
5555
functionality in the standard library
5656
#. posix/bash method naming conventions that linux/unix/osx users are familiar with; or perhaps their Windows variants
5757
#. the existing implementations for the various backends (e.g.,
@@ -62,6 +62,7 @@ to look:
6262
validation code.
6363

6464
.. _os: https://docs.python.org/3/library/os.html
65+
.. _path: https://docs.python.org/3/library/os.path.html
6566
.. _gcsfs: http://gcsfs.readthedocs.io/en/latest/api.html#gcsfs.core.GCSFileSystem
6667
.. _pyfilesystems: https://docs.pyfilesystem.org/en/latest/index.html
6768

‎docs/source/usage.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ remote store, local files, files within some wrapper, or anything else that is c
1212
file-like objects.
1313

1414
Some concrete implementations are bundled with ``fsspec`` and others can be installed separately. They
15-
can be instantiated directly, or the `registry` can be used to find them.
15+
can be instantiated directly, or the ``registry`` can be used to find them.
1616

1717
Direct instantiation:
1818

‎fsspec/archive.py‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,10 @@ class AbstractArchiveFileSystem(AbstractFileSystem):
66
"""
77
A generic superclass for implementing Archive-based filesystems.
88
9-
Currently, it is shared amongst `ZipFileSystem`, `LibArchiveFileSystem` and
10-
`TarFileSystem`.
9+
Currently, it is shared amongst
10+
:class:`~fsspec.implementations.zip.ZipFileSystem`,
11+
:class:`~fsspec.implementations.libarchive.LibArchiveFileSystem` and
12+
:class:`~fsspec.implementations.tar.TarFileSystem`.
1113
"""
1214

1315
def __str__(self):
@@ -19,7 +21,8 @@ def ukey(self, path):
1921
return tokenize(path, self.fo, self.protocol)
2022

2123
def _all_dirnames(self, paths):
22-
"""Returns *all* directory names for each path in paths, including intermediate ones.
24+
"""Returns *all* directory names for each path in paths, including intermediate
25+
ones.
2326
2427
Parameters
2528
----------

‎fsspec/asyn.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
def get_lock():
2525
"""Allocate or return a threading lock.
2626
27-
The lock is allocatted on first use to allow setting one lock per forked process.
27+
The lock is allocated on first use to allow setting one lock per forked process.
2828
"""
2929
global _lock
3030
if not _lock:
@@ -61,8 +61,10 @@ def sync(loop, func, *args, timeout=None, **kwargs):
6161
"""
6262
Make loop run coroutine until it returns. Runs in other thread
6363
64-
Example usage:
65-
fsspec.asyn.sync(fsspec.asyn.get_loop(), func, *args, timeout=timeout, **kwargs)
64+
Examples
65+
--------
66+
>>> fsspec.asyn.sync(fsspec.asyn.get_loop(), func, *args,
67+
timeout=timeout, **kwargs)
6668
"""
6769
timeout = timeout if timeout else None # convert 0 or 0.0 to None
6870
# NB: if the loop is not running *yet*, it is OK to submit work

‎fsspec/caching.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -192,15 +192,15 @@ class BlockCache(BaseCache):
192192
"""
193193
Cache holding memory as a set of blocks.
194194
195-
Requests are only ever made `blocksize` at a time, and are
195+
Requests are only ever made ``blocksize`` at a time, and are
196196
stored in an LRU cache. The least recently accessed block is
197-
discarded when more than `maxblocks` are stored.
197+
discarded when more than ``maxblocks`` are stored.
198198
199199
Parameters
200200
----------
201201
blocksize : int
202202
The number of bytes to store in each block.
203-
Requests are only ever made for `blocksize`, so this
203+
Requests are only ever made for ``blocksize``, so this
204204
should balance the overhead of making a request against
205205
the granularity of the blocks.
206206
fetcher : Callable

0 commit comments

Comments
 (0)