readthedocs documentation (please help!) ⭐️

[syasini]

Add tutorials/documention to readthedocs.

Desperately need help with this!

[zpace]

JOSS reviewer here! (https://github.com/openjournals/joss-reviews/issues/2608)

I strongly suggest you implement some public-facing API documentation on RTD in addition to the (very impressive) information already on the repo's README. If neither your nor other repo developers have done this before and you feel lost, I may be able to offer some help.

[syasini]

This is a great suggestion Zach. I started looking into sphinx and RTD a while ago to implement the API documentation but I found it a bit more complicated than I had originally anticipated. Unfortunately, I still haven't had a chance to look into it again but as you can see in the issue description we do "Desperately need help with this"! :)

We sincerely appreciate and welcome your kind offer to help with the documentation. Please let me know how you would like to proceed.

[zpace]

Hi again, I had an opportunity to start some docs stubs in a fork. These I just created using sphinx's native tools, basically following these guides. If you want, I can make a pull request into this repo, and hand what I have to you. This choice, I think, will make this particular issue go quicker, since this package is on the smaller side. Long-run, you should play around with starting docs from nothing, but this may not be the place for that, if you're feeling time-crunched :smile:.

Let me know if I should make a PR: if so, I can refer you to some next steps.

[syasini]

Thank you so much for putting this together, Zach! I really appreciate the effort. It looks great.

We can definitely go ahead with a PR on this, but I see that your changes have been added to master on your fork. We develop new features on separate branches which after completion are merged into develop, then tested, then merged into master. Ideally, if you could go back in your commit history on master and rebase to a docs branch and submit a PR from zpace:docs to syasini:docs it would be great. I understand if this is too much trouble though.

I have a followup question about developing the docs: Is there a way to automagically extract functions and their docstrings and transfer them to the docs template? I was under the impression that sphinx somehow facilitates this process but last time I played around with it I didn't find a way to do this.

Another note about the docs: I don't know how this will work logistically, but if you'd like to develop and contribute to the documentation we would be more than happy to add you to the collaboration and the paper. We can discuss this via email separately if you want.

[zpace]

Ok, I'll rebase to docs and submit a PR this afternoon. At that point, you can start inserting content into docs/index.rst. This should entail mostly copy-pasting or linking content from your repo's README.md, which already has lots of the info that the docs index should have. Really, you're most of the way there already!

Coming to readthedocs integration, there's some coverage of that in one of those tutorials I linked above. For a smallish package like this, the process should be somewhat straightforward.

As for going docstrings => docs, there is a command, sphinx-apidoc that manages that functionality. That's one of those things I wish was more obvious, so don't feel bad for missing it. As part of the barebones documentation, I've gone ahead and run that command, which put a handful of .md files in docs/source, which should be linked in the docs' TOC. Anytime you add another module, you'll simply rerun that command to generate the markdown!

[zpace]

Oh, also, could you create a docs branch in the base repo? Looks like I cannot do that myself.

[syasini]

Oh nice! That was quick. I appreciate it. And thanks for your encouragement. I'll definitely check out the tutorials and add the contents of the README file to index.rst, but maybe later next week.

I just created a new docs branch. I'll also go ahead and give you access to the repo just in case.

[syasini]

ok, this took a lot longer than I expected but it's finally done! :)

I had to convert the README from md to rst so sphinx can read it—I tried an automated format converter but it didn't work well so I ended up rewriting the code blocks and image sections.

I also linked it to readthedocs which you can see here.

This is only reading the docs branch, but I'll recompile it after I merge everything to master. Let me know if you have any comments.

Thanks again for your help and encouragement.

[zpace]

This looks great: wonderfully done! Once merged to master, feel free to close, and I'll consider online API docs completed for the purposes of JOSS review.

[syasini]

Great! I will merge this to master soon. Thanks again for your help, Zach 🙏

[syasini]

Merged the docs into master and adde a link to the documentation in the README file as well as a docs badge .