ReadTheDocs integration / general doc structure

[ezdac]

Problem definition

So it is really unpleasant to gather a lot of differently structured doc folders containing markdown files in ReadTheDocs (rtds).
Currently we have the python doc (easy), the autogenerated TypeDoc for the client and the autogenerated solidity contract-doc. Also there are README files with additional content and references in the corresponding root folders.

The main problem here being that sphinx/rtds has its own idea of how to convert the folder structure into nodes for further processing, and everything is based on a custom rst directive .. toctree::

This makes it very hard to use nested/linked markdown folder structures that can also work in github.

The recomonmark markdown parser is only laid out in a way that those markdown files work best that don't have any relative links to other files in it, since the toctree directive isn't known here.
Also it is hard to mix rst and md with the .. include:: directive, and here are crossreferences a problem as well.

Suggestion

One solution is to convert the markdown files to rst and parse the links and try to convert it to a toctree structure, but that needs complicated scripts or manual conversion on every change of the docstrings.

What that boils down to:
We should think about using rtds as our main documentation, abandoning the logical nesting of documents in the repositories packages.

• The TypeDoc/Solidity autogenerated docs should be without cross-reference links, only document internal. They should be regarded as leaves in a tree structure.
• definition of the tree-structure / nesting of the documents should be done in the sphinx-folder and should reference the individual files.
• package-README files should provide rather very basic introdution and absolute links to our rtd documentation.

Evaluate

• what options does TypeDoc have to generate simple files without crossreferences, is a custom template needed?

[loredanacirstea]

We should think about using rtds as our main documentation, abandoning the logical nesting of documents in the repositories packages.

I agree with this

From the contracts perspective, everything in contracts/Readme.md can be moved to a main documentation folder. I can have a basic introduction with a link to the docs, as you said.
As for the Solidity generated docs, I will look into it. Plus, I wasn't happy with what I use now - solidity-doc.

[ezdac]

Before we have come up with a solution (also for the js-docs), I will just reference the README files with it's absolute GitHub URL.