ReadTheDocs is awesome for hosting reference docs based on GitHub code. However, we've been bad about ensuring its set up and formatted consistently. Ideally, they would all be like this.

We should do a pass over all of the drivers to ensure that they do these things:

• Have a docs folder with the conf.py moved there. (change sys.path at top of conf.py from '.' to '..') (Adabot verified.)
• Use an docs/index.rst file which includes the README.rst contents and has a table of contents. (Also remove API reference from old README.rst and update conf.py to point to it master_doc = 'index'.) (Adabot verified.)
• Have an examples.rst file which includes all of the example code with titles and brief explanations of what they do. (Adabot verified.)
• Have an updated .travis.yml which will build the docs using sphinx for every PR. Any warnings will cause the Travis run to fail. (Adabot verified.)
  • Add a new folder docs/_static to remove a static warning.
  • Automock any missing modules, such as micropython and busio, in conf.py.
  • Correct any rST syntax errors.
  • Exclude .env and CODE_OF_CONDUCT.md from docs in conf.py.

    exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']

  • Add sphinx.ext.todo to extensions in conf.py and these settings.

    # If true, `todo` and `todoList` produce output, else they produce nothing.
    todo_include_todos = False
    
    # If this is True, todo emits a warning for each TODO entries. The default is False.
    todo_emit_warnings = True

• Add a blinka favicon at docs/_static/favicon.ico and update conf.py to point to it.

  html_favicon = '_static/favicon.ico'

• Rename readthedocs.yml to .readthedocs.yml so its hidden on some systems and listed near .travis.yml
• Have Discord and Travis CI badges (Adabot verified.)
• All images in the README have alt text. This is useful for Adabot finding badges and for screen readers. (Adabot verified.)

I'll follow up with more info below.

If you change example files, please check the Learn guide to see if it's linked

• See the comment below for clarification. Thanks!