Improve developer documentation.

[jeromekelleher]

I started writing some documentation to explain how to write documentation and I ended up doing a merge between the msprime docs and here. Still some way to go, but we do need to get all this stuff down on paper.

Closes #470
Closes #509
Closes #454
Closes #118

[codecov]

Codecov Report

Merging #540 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #540   +/-   ##
=======================================
  Coverage   87.22%   87.22%           
=======================================
  Files          21       21           
  Lines       16283    16283           
  Branches     3195     3195           
=======================================
  Hits        14203    14203           
  Misses       1020     1020           
  Partials     1060     1060           

Flag	Coverage Δ
#c_tests	88.40% <ø> (ø)
#python_c_tests	90.34% <ø> (ø)
#python_tests	99.20% <ø> (ø)

---

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 dd4824e...098d024. Read the comment docs.

[petrelharp]

Super useful. I learned things! Maybe I should have ignored this until you took off the "draft" tag though... ?

[jeromekelleher]

Super useful. I learned things! Maybe I should have ignored this until you took off the "draft" tag though... ?

Yeah, I'm only half way through editing it, but thanks for the comments anyway. I'm going to use the "draft" tag as a "don't bother looking at this yet" protocol.

[jeromekelleher]

This is ready for review now. I changed it a lot, so comments welcome!

[petrelharp]

Looks good! Some minor comments.

[benjeffery]

Really great stuff, just a few nitpicks and broken links. A lot of this I figured out by reading the CI scripts, so nice to have it in proper docs!

[benjeffery]

BTW are the "commit suggestions" helpful? I think they are ok for small things only as they immediately resolve the conversation.

[jeromekelleher]

Note to self: add more on documentation. How to do a quick drive-by edit when you're on github. How to document a function. Links to sphinx and rst docs,.

[benjeffery]

How to do a quick drive-by edit when you're on github.

Why not just add an edit button to each doc page that links to the GitHub edit page?

[benjeffery]

https://gist.github.com/mgedmin/6052926

Seems like readthedocs has support for this? sphinx-doc/sphinx#2386

[jeromekelleher]

To go into the C docs somewhere:

-tsk_id_t is an ID for any entity in a table

• tsk_size_t refers to the size of a table or entity that can be stored in a table
• size_t is an OS size, like the result of strlen or whatever
• Error return types are ints.
• uint32_t etc should be avoided, as these are just leftovers from before tsk_size_t, etc.
• Sometimes we want to do things like work bitstrings (like a set, say), then it makes sense to use in64 or uint64.

[jeromekelleher]

BTW are the "commit suggestions" helpful? I think they are ok for small things only as they immediately resolve the conversation.

Great thanks, I just batched them all together.

[jeromekelleher]

I've made another pass at this, and put a good bit of effort into documenting the documentation process. There's a handholding bit for editing the docs, this is as simple as it can be I think.

Why not just add an edit button to each doc page that links to the GitHub edit page?

Good idea @benjeffery. I've added the "Edit on GitHub" link to the top of the page which seems to work well.

Any chance of another look through helpful reviewers?

[petrelharp]

I haven't had a careful read, but spot-checking, it looks wonderful. :yay:

[jeromekelleher]

OK, squashed and ready to go. @benjeffery, if you're happy can you merge please?

[benjeffery]

I've fixed a broken link, made the git checkout command consistent with the text and added the command to make an upstream remote. Squashed and then force pushed. This time it didn't close the PR! 👍

[benjeffery]

This is awesome and a real step up for the docs. 🌞 Merging!