Use index with an include to include the README but not all of the toc stuff that GitHub doesn't render.

Author: tannewt

.travis.yml

@@ -28,4 +28,4 @@ script:
   - pylint adafruit_pcf8523.py
   - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
   - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-pcf8523 --library_location .
-  - sphinx-build -E -W -c docs -b html . _build/html
+  - cd docs && sphinx-build -E -W -b html . _build/html

README.rst

@@ -27,7 +27,8 @@ temperature compensated alternative, please check out the
 If you need a DS1307 for compatibility reasons, check out our
 `DS1307 RTC breakout <https://www.adafruit.com/products/3296>`_.
 
-.. image:: docs/_static/3295-00.jpg
+.. image:: _static/3295-00.jpg
+    :alt: PCF8523 Breakout Board
 
 Dependencies
 =============
@@ -114,52 +115,3 @@ After the RTC is set, you retrieve the alarm status by reading the
     if rtc.alarm_status:
         print("wake up!")
         rtc.alarm_status = False
-
-Table of Contents
-=================
-
-.. toctree::
-    :maxdepth: 4
-
-    self
-
-.. toctree::
-    :caption: Examples
-
-    docs/examples
-
-.. toctree::
-    :caption: API Reference
-    :maxdepth: 3
-
-    docs/api
-
-
-.. toctree::
-    :caption: Tutorials
-
-    Adafruit PCF8523 Real Time Clock <https://learn.adafruit.com/adafruit-pcf8523-real-time-clock?view=all>
-    Adafruit Adalogger FeatherWing <https://learn.adafruit.com/adafruit-adalogger-featherwing?view=all>
-
-.. toctree::
-    :caption: Related Products
-
-    Adafruit PCF8523 Real Time Clock Breakout <https://www.adafruit.com/product/3295>
-    Adafruit Adalogger FeatherWing - RTC + SD <https://www.adafruit.com/product/2922>
-
-.. toctree::
-    :caption: Other Links
-
-    CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
-    CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
-    Discord Chat <https://adafru.it/discord>
-    Adafruit Learning System <https://learn.adafruit.com>
-    Adafruit Blog <https://blog.adafruit.com>
-    Adafruit Store <https://www.adafruit.com>
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/conf.py

@@ -55,7 +55,7 @@
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'README'
+master_doc = 'index'
 
 # General information about the project.
 project = u'Adafruit\'s PCF8523 RTC Library'

docs/index.rst

@@ -0,0 +1,50 @@
+.. include:: ../README.rst
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 4
+
+    self
+
+.. toctree::
+    :caption: Examples
+
+    examples
+
+.. toctree::
+    :caption: API Reference
+    :maxdepth: 3
+
+    api
+
+
+.. toctree::
+    :caption: Tutorials
+
+    Adafruit PCF8523 Real Time Clock <https://learn.adafruit.com/adafruit-pcf8523-real-time-clock?view=all>
+    Adafruit Adalogger FeatherWing <https://learn.adafruit.com/adafruit-adalogger-featherwing?view=all>
+
+.. toctree::
+    :caption: Related Products
+
+    Adafruit PCF8523 Real Time Clock Breakout <https://www.adafruit.com/product/3295>
+    Adafruit Adalogger FeatherWing - RTC + SD <https://www.adafruit.com/product/2922>
+
+.. toctree::
+    :caption: Other Links
+
+    CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
+    CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
+    Discord Chat <https://adafru.it/discord>
+    Adafruit Learning System <https://learn.adafruit.com>
+    Adafruit Blog <https://blog.adafruit.com>
+    Adafruit Store <https://www.adafruit.com>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`