PyPi links for the README are unreachable

[mariacarmina]

The main README from ocean.py which contains the links to the flows that can be reproduced with the library cannot be accessed from PyPi page.

Problem

The links for the flows are relative paths from ocean.py folder, instead of HTTP links.

Solution

Replace them with HTTP links from GitHub since this is a public repo.

[trentmc]

This is a small problem, but would be nice to solve.

If we replace with absolute links, it introduces a new problem: it makes it harder to debug the readmes locally with the grip tool, because it goes to absolute links of existing readmes rather than the new readmes. In turn, this slows improvements of the readmes.

I only advocate solving the problem in this issue if we don't introduce this new problem.

Perhaps there is a way to solve both at once?

[trentmc]

Fyi this is a known issue of pypi:

pypa/readme_renderer#163

[mariacarmina]

Thank you for the info @trentmc. Then should we add a message in the main README regarding this pypi issue?

[trentmc]

Thank you for the info @trentmc. Then should we add a message in the main README regarding this pypi issue?

I wouldn't bother.

If we can find a fix that works for both, that's ideal. Alas, I don't know of any.

[calina-c]

@trentmc have we ever considered moving the readmes to something like readthedocs.io? Then the main README could just contain a basic description and a link to the readthedocs. Having the READMES moved there would also make for better organisation by topics. The only caveat I see is making sure we are still compatible with the automated readme tests, which I can look into if we decide to follow-up on this.

[trentmc]

@trentmc have we ever considered moving the readmes to something like readthedocs.io?

Well we could, but then that becomes redundant with our regular docs: docs.oceanprotocol.com / github.com/oceanprotocol/docs. We could potentially add more ocean.py-specific documentation to that. However, in my experience, making changes to that has high overhead, which is not the intention of the READMEs right now.

The READMEs are still undergoing churn. At this point in the lifecycle of ocean.py, I don't want to have to update another repo / do another release for every change.

Summary of options of what to do, for now:

1. Do nothing. Pro: highly evolvable docs. Con: pypi links broken
2. In READMEs, make all links absolute. Pro: links work in pypi. Con: hard to debug READMEs
3. In READMEs, put an absolute link next to each symbolic link. Pro: links issue solved. Cons: overhead to maintain two links, ux not great
4. Have just one big README. Stronger use of sections. Pro: links issue solved, evolvable docs. Con: it will be too long so UX will be hard
5. Push much of the stuff to docs.oceanprotocol.com, to be left with just one README. Pro: links issue solved. Con: poorly evolvable
6. Push much of the stuff to readthedocs. Pro: links issue solved. Con: yet another documentation system, poorly evolvable

My recommendation: do (1), ie nothing, and close this issue. We can revisit this later when there is less churn. (>3 mos away)

[trentmc]

Shall we close this issue? (I recommend yes)

[mariacarmina]

yes. I will close this.