Reference Documentation for all Classes and Methods

[cmodzelewski-dynata]

So building off of this great client library for Cmix, I've gone ahead and added a bunch of ReadTheDocs-style docstring documentation and ReStructuredText documentation using Sphinx to the project. I've also made some clean-ups to simplify the release and roll-out of this open source library for when we do future releases of it.

NOTE: All unit tests still pass.

Here are the changes that were made:

Documentation

Reference documentation can be generated locally from the command line by:

1. Updating the installations from requirements to install Sphinx and the Sphinx RTD Theme.

pip install -r requirements.txt

2. Navigating to the docs directory and executing the make html command:

cd docs
make html

You can then view the HTML documentation by opening ../docs/_build/index.html in your web browser.

Setup and Version Tweaks

I slightly tweaked both the setup.py file (and built into the documentation) logic that reads the current version number from a __version__.py file. This ensures that version numbering is consistent between the documentation on the one hand, and the release that would be uploaded to PyPi on the other.

Using Github Actions, this can also be read for automatic release tagging as well.

STILL LEFT TO DO

Note that this is merely the first pass at documenting this library. There are a number of things that I think would help further:

1. We need to confirm that the documentation I included here is accurate. I built it based off of both an in-depth review of the Python source code and by reviewing the Cmix API swagger files...but as we all know, those swagger files are incomplete and may not be up to date.

2. There are a number of places in the documentation where I was uncertain of how to interpret certain things or where I could not find reference documentation in the swagger files. I marked those places as either "TBD" and included .. todo:: call outs to visually indicate (in the rendered documentation) where we need to fill in additional documentation.

3. We should connect the github repo to ReadTheDocs. Since the library is open-source and available under an MIT license, that's straightforward and easy to do. When connected, every time a new push happens it will update the ReadTheDocs documentation (ReadTheDocs is basically the "standard" for the Python community when it comes to documentation).

4. Right now, the README for the repo (and the long description that appears in PyPi.org) is driven by the README.md file. Personally, with all of the other open source libraries I maintain I've had very good experiences using more flexible / verbose reStructuredText to ensure consistency between the GH Repo's README, the PyPi description, and the "home page" for a library's ReadTheDocs documentation. It'll take a tiny bit of tweaking to get this done, but it's something we may want to consider.

5. Right now, this is largely "reference" documentation. It does not yet contain recipes or patterns that show "how to do X" using the library. We should build out some of these examples.

6. The contribution guidelines and the testing overview are largely copy-pasted from other libraries that I maintain and have barely been adapted to the conventions used in this library. There are a couple of slight stylistic convention differences, for example (e.g. E251 from flake8), which - honestly - are largely cosmetic. However, the testing framework documentation needs to be overhauled to provide more guidance on the testing approach.

7. It'd be good to add pytest-cov to measure unit test coverage across the library. We can and should likewise connect the GH repo to codecov or something similar to get coverage badges as well. Nice to have, of course, not need to have.

Anyway - that's it for now - hope this helps, and let me know if we should hop on a Teams call to talk through any of these tweaks / adjustments.

[cmodzelewski-dynata]

1. I have revised the fetch_raw_results documentation to reflect the information which @DynataRidley shared with me.
2. I have built out a "Survey Definition" section which begins to document the Survey Definition format. Note that completing this documentation will involve quite a bit of further effort, but the basic shape of it should be captured here. I have included some "stubbed" pages for other sections which will require more comprehensive documentation.
3. I have updated the contributors listing to reflect that @DynataRidley is the principle maintainer.

In terms of next steps, I would recommend:

1. @DynataRidley reviews the documentation, specifically focusing on the items marked TBD and todo in the docstrings (in api.py and project.py.
2. Once that review is complete, we complete the survey definition documentation. That is something we can potentially do within this PR, or if we want to merge this PR into the main branch we can do it in a separate PR as needed.
3. Following our near-term client conversations, we determine the additional recipes / patterns we want to document.