Expanding documentation

[andrewgy8]

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

[andrewgy8]

#790 Is related

[yozlet]

Huge 👍 to all of this. Thank you for laying that out!

A couple of suggestions:

1. The "Getting Started" doc should discuss use of modelresource_factory before custom Resource classes - see discussion
2. Also related to the above link: how to write tests for your resources (whether factory-generated or custom)
3. I really like the idea of a "common issues/solutions" cookbook-style document, and I have a few tips that could go in there. But it'd also be helpful to delineate those problems that should be solved outside of Django Import/Export, elsewhere in one's data pipeline. Maybe an explanation of the semantics of the API (in the Import Data Workflow) would be useful too.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[matthewhegarty]

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

[matthewhegarty]

I refactored the documentation in 3.1.0. It would be great to update this issue in the light of those changes.

[matthewhegarty]

Also updating documentation significantly in the release-4 branch.

[matthewhegarty]

Documentation has been extensively updated for release-4. I propose to close this and we can open other issues or comment further if extra documentation is required.