Skip to content

Fixes to docs and introduction of doctest

Daniel Wysocki requested to merge daniel.wysocki/gracedb-client:doc-fixes into master
  • Added a new unit test that runs all code examples using doctest
    • This required mocking up GraceDb (to avoid making actual requests, except for fetching some initial data, which it restricts to gracedb-test) and (to pretend files like /path/to/fake/file.xml were real)
  • Fixed many of the code examples which were either stuck on Python 2 syntax or just wrong
  • Removed from io import open in
    • In Python 2 the built-in open was different from Now they are aliases.

Some important caveats:

  • A number of examples are not actually run, using the doctest:+SKIP directive through a trailing in-line comment. This is a potential area for future improvement, but probably fine as-is. Things currently being skipped:
    • Expected HTTP status codes and response bodies did not match the example, given that they were mocked up to do nothing.
    • The GraceDb.files() method would have required a bit more mocking, so I skipped instead
  • Any markup files (e.g., our Sphinx docs) are not run with doctest. This can be added in the future, but would require
    1. Adding the doctest Sphinx extension
    2. Adding the .. doctest:: directive before each example
    3. Figuring out some way to run these tests with our mocked GraceDb class and (probably possible through Sphinx's
  • I did still read over all of the code examples in markup files and confirmed there are no visible errors, including function signature mistakes, though I did not actually run these examples.
  • Each doctest example is potentially creating a new GraceDb session, if it calls GraceDb. We're already doing this in the other unit tests, so it's probably not a huge amount of extra overhead, but there are quite a few of these so we should be careful that we're not negatively impacting service performance.
  • We still use the GraceDb.camelCase versions of methods, which are backwards compatible aliases to our newer, preferred GraceDb.snake_case versions. We probably want to change all of these to avoid encouraging use of old names. We could even cause the unit test to fail if an alias is used instead of the original name.
Edited by Daniel Wysocki

Merge request reports