How to: documentation

[bas-rustenburg]

How to write documentation for scientific software. Discuss tools like read the docs, sphinx, et cetera.

[jchodera]

• Sphinx / RTD examples: protons | ensembler
• Sphinx / S3 examples: mdtraj | pymbar | yank
• Collaborative documentation writing: readme.io
• GitBook

Sphinx material:

• @bas-rustenburg's tutorial on setting up sphinx documentation
• Sphinx tutorial

[jchodera]

autoprotocol has a great example of good changelog documentation using RTD.

[bas-rustenburg]

Thoughts and links on this topic in a nutshell:

• Documentation is the primary way to learn about how code works.
• Clear examples encourage use of code.

There are many tools that can be used to write documentation. The easiest to start with is Github wiki which uses markdown syntax just like the rest of github.

If you need something slightly more powerful, consider using sphinx. Hosting a sphinx project can be tricky on its own, but is almost trivial if you have a public repository, since you can use readthedocs.

If you're using conda for your code, you may want to check out a step to step guide on setting up a conda project with read the docs, here.

[bas-rustenburg]

https://guides.github.com/features/wikis/ Helpful guide on Github wikis .

[bas-rustenburg]

A template for sphinx/read the docs https://github.com/readthedocs/template

[bas-rustenburg]

wiki example: https://github.com/d3/d3/wiki

Sphinx examples: https://github.com/choderalab/yank/tree/master/docs https://github.com/pymc-devs/pymc/tree/master/docs

[jchodera]

Addressed in #28