Update and unify documentation
We currently have 2 places where there is documentation related to soledad:
- https://leap.se/en/docs/design/soledad - from leap_se repository, written in markdown, compiled by amber.
- https://soledad.readthedocs.io/en/latest/ - from soledad repository, written in reStructuredText, compiled by sphinx.
Much of the doc in (1) is not well organized and outdated. (2) is currently more up-to-date, and a bit more organized.
Some things have to be done:
-
review and update current info on (1), merge it into (2) (is needed and will be useful anyway we go afterwards). -
review the structure of (2) given some research about doc and the current content of (1) and (2). -
unify (1) and (2) -- see below for options.
It seems there are at least 2 different memories of this discussion in the past:
- to centralize all the technical docs in leap.se
- to centralize all the project's docs in leap.se, and to maintain library docs where suitable. I plan to keep updating (2) and eventually move away from sphinx or keep sphinx and make it produce pages in leap.se.
I think the important decision is which of the two above we will go with, and the rest is implementation details.
Things to take into account:
- it is very useful for grant applications and for promoting LEAP as an organization to have a central website that has all the technical documentation in one place.
- documentation should be easy to be found.
- all the doc should be updated from the soledad repository because it's easier to maitain the relation of code and documentation.
- there should not exist more than one version of the same documentation (even if it is replicated in more than one place).
- we would like to have api documentation generated from source code.
Edited by drebs