Add readthedocs documentation to Scribe-Data

[andrewtavis]

Terms

• I have searched open and closed feature requests
• I agree to follow Scribe-Data's Code of Conduct

Description

This issue would be to add in readthedocs for Scribe-Data. Goal would be to have all functions and classes automatically documented.

• Note that this issue is linked to Standardize function doc strings across Scribe-Data #56 😊

Contribution

Happy to support with this! We should discuss implementation beforehand, but I've used readthedocs extensively for other projects and am happy to help with setup or add parts to the docs.

[andrewtavis]

CC @m-charlton 😊 Let me know how you'd like to start on this!

[shashank-iitbhu]

assign @andrewtavis

[andrewtavis]

Thank you @shashank-iitbhu!

[m-charlton]

Apologies for the late reply. Started to look at this late last year but, other things got in the way. Will gather my notes and lay out a plan of action

…

On 14 Nov 2023, at 08:10, Andrew Tavis McAllister ***@***.***> wrote: CC @m-charlton <https://github.com/m-charlton> 😊 Let me know how you'd like to start on this! — Reply to this email directly, view it on GitHub <#57 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABVUVP7OMREQGKJFISOA5OTYEMRPVAVCNFSM6AAAAAA7KMAXWOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMBZG4YTQNJSGA>. You are receiving this because you were mentioned.

[andrewtavis]

Great to hear from you, @m-charlton! Plan is to get the baseline for this up for @shashank-iitbhu later today. We can talk about this here in the issue and also check into the work for the doc strings in #56 :)

[andrewtavis]

Ok all 😊 We now have the base docs available at scribe-data.readthedocs.io, and the GitHub integration is working fine on commits to the repo 🙌 In setting it up, for some reason the modules weren't being loaded in though. I'm wondering if maybe we didn't have the current __init__.py structure when the last release was made? Not sure. My assumption is that the following in utils.rst should work:

utils
=====

The :py:mod:`utils` module provides utility functions for data extraction, formatting and loading.

.. automodule:: scribe_data.utils
    :members:
    :private-members:

What we're getting though is:

WARNING: autodoc: failed to import module 'utils' from module 'scribe_data'; the following exception was raised:
No module named 'scribe_data.utils'

Similarly for checkquery. Let's share some thoughts, and then I think we should be good to try out automodule with other files. Note that we are using numpydoc as of now, so for #56 some of the docstrings might need to be changed. If others have a suggestion on other doc styles we can definitely make a change though!

[andrewtavis]

CC @wkyoshida :)

Another thing to consider is that it'd be good to set it up with a Edit on GitHub link or something like that in the top right rather than the View source (not too much value there I'd say). This can be a separate issue though if we want 😊

[andrewtavis]

I would say in general a couple more links to GitHub in there would be good. Maybe something in the left sidebar as well?

[andrewtavis]

Also of note, here's an awesome list for readthedocs for examples: github.com/readthedocs-examples/awesome-read-the-docs. I think that for this issue we can focus on finalizing getting all the function docstrings in here along with #56, and then we can make a few more issues for customizing it a bit with things like a logo in the sidebar, etc.

[andrewtavis]

Very long day of work on this to get it ready for docs and the next steps for GSoC, but we're basically there 😊 One minor release and two patches to get it all cleaned up and the docs working in a day 🚀

Where we're at for the documentation can be seen at scribe-data.readthedocs.io. I did some basic organizing, and autodoc/automodule is working. We can now apply this over the rest of the project and then this issue will be finished :)

Of note is that I got rid of the conda environment and we're now using Python venv (docs have been updated). Was necessary to do a release so that tensorflow wouldn't needlessly be installed when we install Scribe-Data for the docs. To get the venv up and running we can do the following:

# In the root of the project:
python3 -m venv venv  # make an environment venv
pip install --upgrade pip  # make sure that pip is at the latest version
pip install -r requirements.txt  # install dependencies

If you're using VS Code, then it should prompt you to select this as the default environment. From there restart the terminal session in VS Code to then see that you're in the venv.

To get the docs up and running:

cd docs
make html

You can then open index.html within docs/build/html to check the local version of the documentation.

Note also that one of the changes that went through is that the baseline data files from Wikidata are removed once the formatted JSON file is finished.

Let's discuss all of this in the sync! 😊

[andrewtavis]

Hey @shashank-iitbhu 👋 Do you want to send the autodoc/automodule calls to finalize the documentation and we can close this?

[andrewtavis]

.. automodule:: scribe_data.utils
    :members:
    :private-members:

[shashank-iitbhu]

Hey @shashank-iitbhu 👋 Do you want to send the autodoc/automodule calls to finalize the documentation and we can close this?

Looking into this!

[shashank-iitbhu]

In conf.py the sys.path is this:

sys.path.insert(0, os.path.abspath(".."))

don't you think, it should be :

sys.path.insert(0, os.path.abspath("../../src"))

currently getting this error, when i do cd docs && make html :

After updating the path to ../../src
i was able to generate docs for all the functions in checkquery.py and utils.py.

[shashank-iitbhu]

Am I missing something? cc @andrewtavis

[andrewtavis]

Closed via 18046e3 🥳 Definitely will need to be updated as we go, but this we finally have a baseline for the documentation for Scribe-Data! 🙌 Thanks all so much for your contributions!