ocean.py: not testable -> leads to bugs -> leads to high friction. And, DRY violation

[trentmc]

The problem

In ocean.py repo, after great effort, we have CI infrastructure to auto-test the READMEs. This ensures that they are always working. So when we make changes, we'll know immediately if a mistake was made. And then people looking to use ocean.py aren't subjected to README bugs.

The docs repo, ocean.py section replicates the READMEs. The idea was to "reduce friction". But the opposite happens: it adds great risk of bugs, which therefore adds way more friction.

• Details: In practice it's tedious and error-prone to keep the "docs" version up-to-date with "ocean.py repo" version. And we don't have any good way to test it except manually go through everything, which is highly time-consuming. So ocean.py in "docs" can easily get out of date, and have errors. Therefore people looking to use ocean.py by following "docs" are subjected to README bugs -- and this is extremely high friction.
• We shouldn't be surprised by this. The "docs" version is a massive DRY violation. Anytime one sees such a DRY violation, one can expect errors to emerge; it's happening here.

Put another way: status quo tried to reduce friction, but the result greatly increases it (because bugs)

Relevant datapoints

• ocean.py is currently basically in maintenance mode, by S3.
• S3's main focus is Predictoor (not ocean.py) because it's a far higher bang-for-buck traction opportunity.
• Therefore this ticket is not urgent

Candidate solutions

1. Leave as-is. Do try to keep docs up-to-date with ocean.py. Pro: little up-front effort. Con: not sustainable if big changes to ocean.py
2. Docs pass-through. Have just a single ocean.py page in docs, as a fat pass-through to the READMEs in ocean.py repo.
3. Docs using ocean.py README code. In gitbook docs, find a way to auto-import key README code from ocean.py
4. ocean.py has its own docs. Move gitbook functionality into ocean.py; move all the existing docs content there. Reconcile that content with ocean.py READMEs to (a) remove DRY violations (b) ensure it's all tested. In main docs repo, have a fat-pass through to the ocean.py repo's docs.
5. other ideas?

Discussion

• (1) is the most pragmatic for now given that ocean.py is in maintenance mode
• For the future, (2)-(5) are all on the table

[trentmc]

Closing this, since it's not gonna happen anytime soon. Can revisit when we do.