Expanding documentation

Let me start of by saying that I think our documentation is great. However, I do believe there is room for improvement, and Id be willing to take on the task of improving it. What do you all think about polishing up and expanding our documentation?

Somethings I have considered so far:

• Clarify the Import Data Workflow section by providing a high level overview followed by the more lower level overview.
• Add an Export Data Workflow section. It might seem strange to the user that we have one, but not the other.
• Reviewing previous issues that provide good fixes to common problems. We can create a common issues/solutions section to place all this stuff in.
• In our doc strings we should emphasize the why? as well the what?. Django does this well for some of their docs.
• Clearly mention known implementation limitations.
• Add a contributing section that can explain in detail how to fork, install and run the tests against any of our supported DB’s (sqlite, postgres, mysql).
• We can clarify the DB’s that we support.
• Expanding doc strings. The hardest (and still kind of is) part for me when I joined this project, was the lack of documentation on some of the classes, such as ModelDeclarativeMetaclass. I think it would be nice if we describe what that class does, and why its important.

I have been reading this, so I’ll try to follow those guidelines as I move forward.

Any other areas where you think we can improve?

Also, I’m unfamiliar with readthedocs.io, but are the docs compiled locally and then uploaded to the site? Or is this integrated into the CI? If not, do we want it integrated into the CI?

[bmihelac]

@andrewgy8 this sounds fantastic!

regarding readthedocs, I have updated integration to use webhooks, RTD should automatically create on push and branch create/delete actions. Ref: https://docs.readthedocs.io/en/latest/webhooks.html#github

[matthewhegarty]

Better documentation of API objects is required (see #1322).