Improve the docs.

Author: tannewt

README.rst

@@ -10,13 +10,18 @@ Introduction
     :target: https://gitter.im/adafruit/circuitpython?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
     :alt: Gitter
 
-TODO
+.. image :: https://img.shields.io/discord/327254708534116352.svg
+    :target: https://adafru.it/discord
+    :alt: Discord
+
+CircuitPython driver for SD cards. This implements the basic reading and writing
+block functionality needed to mount an SD card using `storage.VfsFat`.
 
 Dependencies
 =============
 This driver depends on:
 
-* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Adafruit CircuitPython 2.0.0+ <https://github.com/adafruit/circuitpython>`_
 * `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
@@ -26,7 +31,31 @@ This is easily achieved by downloading
 Usage Example
 =============
 
-TODO
+Mounting a filesystem on an SD card so that its available through the normal Python
+ways is easy.
+
+Below is an example for the Feather M0 Adalogger. Most of this will stay the same
+across different boards with the exception of the pins for the SPI and chip
+select (cs) connections.
+
+.. code-block:: python
+
+    import adafruit_sdcard
+    import busio
+    import digitalio
+    import board
+    import storage
+
+    # Connect to the card and mount the filesystem.
+    spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
+    cs = digitalio.DigitalInOut(board.SD_CS)
+    sdcard = adafruit_sdcard.SDCard(spi, cs)
+    vfs = storage.VfsFat(sdcard)
+    storage.mount(vfs, "/sd")
+
+    # Use the filesystem as normal.
+    with open("/sd/test.txt", "w") as f:
+        f.write("Hello world\n")
 
 Contributing
 ============

adafruit_sdcard.py

@@ -21,7 +21,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_sdcard`
+`adafruit_sdcard` - SD card over SPI driver
 ====================================================
 
 CircuitPython driver for SD cards using SPI bus.
@@ -31,15 +31,18 @@
 
 Example usage:
 
+.. code-block:: python
+
     import busio
-    import filesystem
+    import storage
     import adafruit_sdcard
     import os
     import board
 
     spi = busio.SPI(SCK, MOSI, MISO)
     sd = adafruit_sdcard.SDCard(spi, board.SD_CS)
-    filesystem.mount(sd, '/sd2')
+    vfs = storage.VfsFat(sdcard)
+    storage.mount(vfs, '/sd')
     os.listdir('/')
 
 * Author(s): Scott Shawcroft
@@ -63,6 +66,10 @@
 _TOKEN_DATA = const(0xfe)
 
 class SDCard:
+    """Controls an SD card over SPI.
+
+        :param ~busio.SPI spi: The SPI bus
+        :param ~digitalio.DigitalInOut cs: The chip select connected to the card"""
     def __init__(self, spi, cs):
         # This is the init baudrate. We create a second device for high speed.
         self._spi = spi_device.SPIDevice(spi, cs, baudrate=250000, extra_clocks=8)

conf.py

@@ -15,7 +15,12 @@
     'sphinx.ext.viewcode',
 ]
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'BusDevice': ('https://circuitpython.readthedocs.io/projects/bus_device/en/latest/', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
+
+autodoc_mock_imports = ["adafruit_bus_device", "micropython"]
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),
+                       'BusDevice': ('https://circuitpython.readthedocs.io/projects/bus_device/en/latest/', None),
+                       'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -26,7 +31,7 @@
 master_doc = 'README'
 
 # General information about the project.
-project = u'Adafruit SDCARD Library'
+project = u'Adafruit SD Card Library'
 copyright = u'2017 Scott Shawcroft'
 author = u'Scott Shawcroft'
 
@@ -91,7 +96,7 @@
 html_static_path = ['_static']
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'AdafruitSDCARDLibrarydoc'
+htmlhelp_basename = 'AdafruitSD CardLibrarydoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -117,7 +122,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'AdafruitSDCARDLibrary.tex', u'Adafruit SDCARD Library Documentation',
+    (master_doc, 'AdafruitSD CardLibrary.tex', u'Adafruit SD Card Library Documentation',
      u'Phiilip Moyer', 'manual'),
 ]
 
@@ -126,7 +131,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'adafruitSDCARDlibrary', u'Adafruit SDCARD Library Documentation',
+    (master_doc, 'adafruitSD Cardlibrary', u'Adafruit SD Card Library Documentation',
      [author], 1)
 ]
 
@@ -136,7 +141,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'AdafruitSDCARDLibrary', u'Adafruit SDCARD Library Documentation',
-     author, 'AdafruitSDCARDLibrary', 'One line description of project.',
+    (master_doc, 'AdafruitSD CardLibrary', u'Adafruit SD Card Library Documentation',
+     author, 'AdafruitSD CardLibrary', 'One line description of project.',
      'Miscellaneous'),
 ]