Write ArviZ docs guide

[roshnaeem]

Description:

• Restructuring developer guide to separate documentation guide from it.
• Updating doc guide to add more sections.

[codecov]

Codecov Report

Merging #1903 (e291e63) into main (0c9da0f) will not change coverage.
The diff coverage is n/a.

❗ Current head e291e63 differs from pull request most recent head 586dce7. Consider uploading reports for the commit 586dce7 to get more accurate results

@@           Coverage Diff           @@
##             main    #1903   +/-   ##
=======================================
  Coverage   91.51%   91.51%           
=======================================
  Files         113      113           
  Lines       12231    12231           
=======================================
  Hits        11193    11193           
  Misses       1038     1038           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0c9da0f...586dce7. Read the comment docs.

[OriolAbril]

The main challenge here is defining the audience of these documents and setting their structure. I would first work on an outline detailing what you intend to cover and how are you planning to structure it, work on that at this level and then start writing and actually filling in the outline.

We also have to think about perception and biases we might end up adding on that structure. i.e. completely separating developer from doc guide can give the impression that people can work on new code features without working on documentation which is not the case, one thing is fixing an issue and consequently working only on code, but unlike when adding new doc pages which can be done on its own, adding a new feature requires writing the corresponding documentation in the same way tests need to be written too. On the other hand however, separating them can indicate that people can work on documentation without having to write code.

I am sorry a lot of the feedback is vague and non-actionable at least not without a discusion before. I am also bound to change my advise, I don't have the answers to most of the questions here. We have to experiment, try things out, discuss them and see what works best.

[OriolAbril]

many comments reference other comments. Comments should be read all at once at least the first time before answering any or starting any changes.

[OriolAbril]

I don't know what you thought about this section when you read it, but I think it needs to be rewritten. When I wrote it I barely understood sphinx cross-referencing and wrote all that mostly for myself. Now the separations between intersphinx or internal references, or even between ref/doc or func/meth/mod/class... ones feel forced and mostly confusing.

[OriolAbril]

will do at some point in a follow up PR, or remove it and link to sphinx-primer