[JOSS] ReadTheDocs pages

[AJQuinn]

Hello - one weakness in this (otherwise excellent) repo is the readthedocs pages here: https://spectral-connectivity.readthedocs.io/en/latest/ - these seem rushed and a bit of an afterthought.

One concern is that the build generates a really large number of warnings and exceptions listed in the final tab here https://readthedocs.org/projects/spectral-connectivity/builds/18509808/

some examples

/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/spectral_connectivity/transforms.py:docstring of spectral_connectivity.transforms.Multitaper.n_tapers:1: WARNING: duplicate object description of spectral_connectivity.transforms.Multitaper.n_tapers, other instance in _autosummary/spectral_connectivity.transforms.Multitaper, use :noindex: for one of them
/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/spectral_connectivity/transforms.py:docstring of spectral_connectivity.transforms.Multitaper.n_time_samples_per_step:1: WARNING: duplicate object description of spectral_connectivity.transforms.Multitaper.n_time_samples_per_step, other instance in _autosummary/spectral_connectivity.transforms.Multitaper, use :noindex: for one of them
/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/spectral_connectivity/transforms.py:docstring of spectral_connectivity.transforms.Multitaper.tapers:1: WARNING: duplicate object description of spectral_connectivity.transforms.Multitaper.tapers, other instance in _autosummary/spectral_connectivity.transforms.Multitaper, use :noindex: for one of them
WARNING: autodoc: failed to import module 'setup'; the following exception was raised:
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/envs/latest/lib/python3.9/site-packages/sphinx/ext/autodoc/importer.py", line 58, in import_module
    return importlib.import_module(modname)
  File "/home/docs/.asdf/installs/python/3.9.13/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 850, in exec_module
  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed
  File "/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/setup.py", line 26, in <module>
    long_description=open("README.md").read(),
FileNotFoundError: [Errno 2] No such file or directory: 'README.md'

/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/docs/source/spectral_connectivity.rst:20: WARNING: Citation [Rce5454392c8c-1] is not referenced.
/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/docs/source/spectral_connectivity.rst:22: WARNING: Citation [R50ceabb4b5b7-1] is not referenced.
/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/docs/source/spectral_connectivity.rst:10: WARNING: Citation [R92db3e0bed67-1] is not referenced.
/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/docs/source/spectral_connectivity.rst:32: WARNING: Citation [Reea3610c2217-1] is not referenced.
/home/docs/checkouts/readthedocs.org/user_builds/spectral-connectivity/checkouts/latest/docs/source/spectral_connectivity.rst:16: WARNING: Citation [Rd62c8e2568d7-1] is not referenced.
done

Perhaps not a major issue on its own but suggests that the build is fairly fragile and likely missing some details. Could you take a look and fix up some of these issues?

I've tried to make a local build to say something more productive but keep running into a docutils error.

xref: https://github.com/openjournals/joss-reviews/issues/4840

[AJQuinn]

It would also be great to include more information on the docs page - some of this is duplicated in the README file but should be consistent across github and readthedocs if both are maintained. Currently a user landing on readthedocs could get a bit lost...

Can you look into adding/fixing:

• [x] Installation instructions
• [x] Details about bug reporting or making code contributions
• [x] Module level docstrings to add more info on the API pages: https://spectral-connectivity.readthedocs.io/en/latest/_autosummary/spectral_connectivity.html
• [x] The jupyter tutorial pages seem to be empy - should be linked to relevant pages: https://spectral-connectivity.readthedocs.io/en/latest/tutorials.html
• [x] Grammar and capitalisation on landing page aren't great, seems like points should be rendered as a list perhaps? https://spectral-connectivity.readthedocs.io/en/latest/index.html

[edeno]

Hi @AJQuinn , I believe I have fixed all these issues in the documentation. Please reopen the issue if you feel that these haven't been fixed. I am working on the usage examples for the other issue.