Improve our reference docs

[tannewt]

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!

[willingc]

Have an updated .travis.yml which will build the docs using sphinx for every PR.

Once a month, maybe by scheduled cron job, run make linkcheck on all the docs.

[willingc]

Just an FYI for future docs, you may want to check out sphinx-gallery for examples: https://sphinx-gallery.github.io/index.html

[sommersoft]

Assigned myself, but anyone feel free to jump in. @ me if you start one so I can mark it, or if you get one completed and need it marked as complete.

So, I took step one and made a list of the current drivers in the bundle. Then, went through each one to see if any were already completed (knew it would be a short list).

At any rate, here's the task list:

DRIVERS

• ads1x15
• amg88x
• apds9960
• bme280
• bme680
• bmp280
• bno055
• ccs811
• charlcd
• circuitplayground
• dht
• dotstar
• drv2605
• ds1307
• ds18x20
• ds2413
• ds3231
• fingerprint
• fxas21002c
• fxos8700
• gps
• ht16k33
• ina219
• irremote
• is31fl3731_2
• lis3dh
• lsm9ds0
• lsm9ds1
• max31855
• max31865
• max7219
• max9744
• mcp4725
• mcp9808
• mma8451
• mpr121
• neopixel
• pca9685
• pcf8523
• rfm69
• rgb_display
• sdcard
• seesaw
• sgp30
• sht31
• si5351
• si7021
• ssd1306
• tcs34725
• thermal_printer
• thermistor
• tlc5947
• tlc59711
• trellis
• tsl2561
• tsl2591
• vc0706
• vcnl4010
• veml6070
• vl6180x
• vl53010x

HELPERS

• avrprog
• bus_device
• fancyled
• featherwing
• hid
• motor
• onewire
• register
• rtttl
• simpleio
• waveform

[sommersoft]

README Badges: some have Gitter some don't. Do we want all, some, or none to have it?

[tannewt]

@sommersoft I remove them in favor of the Discord badge when I come across them.

[sommersoft]

Realized a small(?) problem. By getting image files in the repos to pass Sphinx builds (.. image:: ../blah/blah.jpg), they no longer show up in GitHub.

Here is what I have so far

• CircuitPlayground: images were in top/_static/. I moved them to top/docs/_static and updated README with the appropriate path. Images show in RTD build, but do not show in GitHub. My PR was merged, so RTD should reflect my changes.

• DS1307: image was in top/. I originally left it there, and got Sphinx to eventually build using .. image:: ../image.jpg. Moved on to next lib to work, then it popped in my head to check. GitHub is no longer showing the image (PR isn't merged yet, so I can't check RTD). Not fully understanding the problem, I moved the image to top/docs/_static and updated README. That's when I went back to check CircuitPlayground to verify...

• DS3231: (updating original comment) Same as DS1307 above. Just to keep track of where the images are.

I don't remember any other libraries having images that I've done so far, but I'll check. (update: no others effected before CircuitPlayground)

Since we're using the README.rst for both GitHub and RTD, the only way I see having images in both places is to use a .rst and a .md version. Granted, my Sphinx knowledge is barely basic...

[sommersoft]

Should we close this, now?

[kattni]

We still have some updates to make. Here's the Adabot report:

Missing license. -

• Adafruit_CircuitPython_LSM303
• Adafruit_CircuitPython_TSL2561
• Adafruit_CircuitPython_APDS9960
• Adafruit_CircuitPython_DHT

Not in bundle. -

• Adafruit_CircuitPython_FocalTouch

Missing CODE_OF_CONDUCT.md -

• Adafruit_CircuitPython_MCP9808
• Adafruit_CircuitPython_CCS811
• Adafruit_CircuitPython_DS1307

ReadTheDocs latest build has warnings and/or errors -

• Adafruit_CircuitPython_AMG88xx
• Adafruit_CircuitPython_LSM303
• Adafruit_CircuitPython_AVRprog
• Adafruit_CircuitPython_VL6180X
• Adafruit_CircuitPython_VL53L0X
• Adafruit_CircuitPython_Thermal_Printer
• Adafruit_CircuitPython_OneWire
• Adafruit_CircuitPython_TCS34725
• Adafruit_CircuitPython_VCNL4010
• Adafruit_CircuitPython_CharLCD
• Adafruit_CircuitPython_LSM9DS0
• Adafruit_CircuitPython_INA219
• Adafruit_CircuitPython_MPR121
• Adafruit_CircuitPython_APDS9960
• Adafruit_CircuitPython_Fingerprint
• Adafruit_CircuitPython_LSM9DS1
• Adafruit_CircuitPython_MAX31865
• Adafruit_CircuitPython_seesaw

README missing Travis badge -

• Adafruit_CircuitPython_FocalTouch
• Adafruit_CircuitPython_VEML6070
• Adafruit_CircuitPython_LSM303

Autodoc failed on ReadTheDocs. (Likely need to automock an import.) -

• Adafruit_CircuitPython_AMG88xx
• Adafruit_CircuitPython_VL53L0X
• Adafruit_CircuitPython_TCS34725
• Adafruit_CircuitPython_VCNL4010
• Adafruit_CircuitPython_CharLCD
• Adafruit_CircuitPython_LSM9DS0
• Adafruit_CircuitPython_INA219
• Adafruit_CircuitPython_APDS9960
• Adafruit_CircuitPython_Fingerprint
• Adafruit_CircuitPython_LSM9DS1
• Adafruit_CircuitPython_MAX31865
• Adafruit_CircuitPython_seesaw

Missing .py files in examples folder -

• Adafruit_CircuitPython_LSM303
• Adafruit_CircuitPython_FeatherWing

Sphinx missing files -

• Adafruit_CircuitPython_CharLCD
• Adafruit_CircuitPython_MPR121

README image missing alt text -

• Adafruit_CircuitPython_DS3231

[willingc]

Great work folks. Moving things forward well.

[sommersoft]

As you can see by its inclusion in almost all categories, LSM303 & FocalTouch need the Full Monty. They were added after I compiled the task list, and I didn't go back and see what was added during the 2 week docstravaganzo.

Preliminary "check the checker" results for the autodoc failures: all of those RTD builds are over a month old, and aren't for the new doc structure. Also, CharLCD is still giving a 404... I'm working on a full scale report; may take a couple days.

[kattni]

Brilliant, thank you!

[tannewt]

Are there doc builds that I need to poke? Its possible the webhooks are setup correct and so they are out of date and therefore look like they are failing.

[sommersoft]

@tannewt CharLCD has been out of commission for some time... It appears that most, if not all, of the ones in the 'autodoc failed' section are older builds (1+ month). I will get a full list together shortly.

[tannewt]

I checked and fixed all the build issues except APDS9960 which is failing due to a data descriptor getting passed a mock object I think.

[sommersoft]

Missing .py files in examples folder -

• Adafruit_CircuitPython_FeatherWing

FeatherWing example.py files are nested in subdirectories. Should we figure out a way to have adabot check nested folders, or maybe just put a dummy/general .py in the examples/ folder?

Autodoc failed on ReadTheDocs. (Likely need to automock an import.) -

• Adafruit_CircuitPython_APDS9960

For the APDS9960, do you want me to remove the const on the APDS9960_ENABLE assignment? I just hope it doesn't waterfall for all of the others and we just keep chasing it down the line.

Sphinx missing files -

• Adafruit_CircuitPython_CharLCD
• Adafruit_CircuitPython_MPR121

I think these two should be good now after the new builds. I checked their RTDs, and all seems well. Just don't want to mark them complete since I didn't do anything with them..

[kattni]

I noticed the FeatherWing issue. If we can update Adabot to check subfolders, that's great, but I think in the case of FeatherWing, it might still be a good idea to have a readme.py in that folder anyway since it's an unusual library. Something explaining that each folder contains examples to go along with the associated FeatherWing.

We'll need to test it if we remove const but I think we should. We need to make sure it gets tested and doesn't sit for ages, though. And, if it's something we have to chase, then we chase it. Once we've chased it to the end, it'll be over and we can do as we like moving forward. I'll defer to Scott on this one if he has a differing opinion.

Thanks for the update!

[tannewt]

We can updated Adabot to be ok with subfolders. I think a README.md would be fine but I don't think a .py makes sense.

I'll take a quick look now at APDS9960 and see if I can get a better mock function in there. I think another library may have done it already.

[tannewt]

Here is a fix for APDS9960: adafruit/Adafruit_CircuitPython_APDS9960#8

We can use the same technique to remove any MockObjects we see references in the auto-gened docs.

Great work everyone!

[sommersoft]

I agree on both accounts. A README would be useful in the FeatherWing examples folder, but a .py might get confusing. Would RTD render a .md (lazy/at work; haven't looked it up myself)? If not, we could setup a toctree for the examples with an examples.rst, or sub-tree it in the index.rst.

[tannewt]

I believe RTD would render the .md unless we explicitly ignore it.

…

On Mon, Mar 19, 2018 at 8:46 AM sommersoft ***@***.***> wrote: I agree on both accounts. A README would be useful in the FeatherWing examples folder, but a .py might get confusing. Would RTD render a .md (lazy/at work; haven't looked it up myself)? If not, we could setup a toctree for the examples with an examples.rst, or sub-tree it in the index.rst. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#566 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AADNqcrCIRhxgtJTaus9xyRjR5LY0D0Eks5tf9LFgaJpZM4RzRbj> .

[willingc]

I believe @tannewt is correct. If you do not for some reason see it, double check that it is included in any toctree (local or master) and that recommonmark is installed.

[tannewt]

Isn't this done?

[sommersoft]

@tannewt I think the only thing left from the lists above, is taking care of the FeatherWing example "readme". Other than that, guess it depends on what adabot is still complaining about...

[tannewt]

I don't think we'll get to zero, we'll just hover around it. Thanks for getting us close! I'll close this and we can do more Adabot driven stuff in new issues as needed.