Documentation

[JtotheThree]

I'm interested in helping with documentation.

My initial proposal

• Use https://readthedocs.org/ to host and Sphinx for auto documentation
• There seems to be a desire to keep the project as simple to contribute to as possible, so we would stick with .md instead .rst
• md files would stay in the root docs folder
• We may need to clean up docstrings but I can see what we can do about not requiring strict docstrings? https://github.com/jldbc/pybaseball/issues/125

Let me know if there's no desire to use Read the Docs

[schorrm]

I think there doesn't seem to be a strong desire at the moment to move over to something like this. Other contributors of course are free to weigh in.

[reddigari]

I'm a huge fan of Sphinx/RTD and think it's a terrific idea, but the effort might outweigh the benefit. IMHO a big advantage of Sphinx and autodoc is that the docstrings become the single source of truth (rather than having to simultaneously maintain function signatures in the docs/ directory). Leaving all the markdown there for the sake of ease-of-contribution might defeat the purpose a little (but that's just the opinion of a negligible contributor). Feels like if one were to tackle this it would require a substantially different approach to documentation going forward, including automated CI checks enforcing strict docstrings.

FWIW I know there are markdown-to-ReST conversion tools that could be used tin the Sphinx build to take advantage of what's already in docs/.