Suggestions for maintenance updates

[hakonanes]

Thank you @vaipatel for the positive experience of contributing to this package!

As mentioned in #13, I want to reference this package in a manuscript. Therefore, I want this package to be easily maintainable in the foreseeable future. With this in mind, I have a few suggestions for maintenance updates I'd like to discuss:

• Use tox in the GitHub Actions build CI with tox-gh-actions. #15
• Use the clean and OS dark/light theme aware RtD theme Furo instead of the "standard" RtD theme. See comment Suggestions for maintenance updates #14 (comment)
• Use the README.rst directly in the RtD docs' index.rst (example use), without going via a Sphinx make command. The setup you had with README_for_gh is nice.
• Make a changelog based on Keep a Changelog. Here's an example from one of the projects I maintain (RtD docs, source). See Add changelog and other minor documentation changes #16.
• Add a GitHub Action to automatically package and upload the source distribution to PyPI upon a tagged release via GitHub (example). See Automatically upload source dist to PyPI on tagged GitHub release #17.
• Make package downloadable via conda channel conda-forge (example). See Add morphops Python package conda-forge/staged-recipes#16430.
• Add all-contributors section to express thanks to contributors
• Make RtD build the documentation on PR checks (as explained in their documentation). A badge displaying whether the doc build passes or not can be added to README.rst.
• Set up line coverage checks on PRs via Coveralls (example). A badge displaying the coverage can be added to README.rst.
• Add a Zenodo DOI that automatically updates when a new tagged release is made via GitHub (example). An explainer in the GitHub docs. A badge with a link can be added to README.rst.

Feel free to edit this comment to add to the list.

If there is interest, I can make PRs for most of these points. Some points require access I don't have though: the RtD build on PR, set up Coveralls, Zenodo DOI. I can assist with these if desirable.

[vaipatel]

Hey @hakonanes. That's an awesome maintenance list, don't know what more to say! Thanks for putting it together.

I just put the ones that require access at the bottom for now, hope it doesn't trip your flow. Only because I might be slower to get to them/will probably need an assist, but I do like them. Perhaps we can revisit those (if you're still interested then of course)?

Other than that my only contribution here was adding one item for myself - to add an allcontributors section.:)

[hakonanes]

Turns out the furo theme needs sphinx v4, but the current docs are built with v1.8.5. Tried building the docs without modifications with furo and Sphinx v4, but this doesn't work, meaning I needed to list the module functions by hand. If this is acceptable, I'll set up a PR. If not, I'm unfortunately not familiar enough with making templates for Sphinx to avoid listing functions manually, so I'll drop updating the theme.

[hakonanes]

I just put the ones that require access at the bottom for now, hope it doesn't trip your flow. Only because I might be slower to get to them/will probably need an assist, but I do like them. Perhaps we can revisit those (if you're still interested then of course)?

Making RtD build docs from PRs is particularly easy, just ticking a box! It would be good to tick the box so that RtD build the docs from PRs when I set up a PR with some suggested doc changes.

Other than that my only contribution here was adding one item for myself - to add an allcontributors section.:)

Great, we use that in a project I maintain as well.

[vaipatel]

RtD's "Build pull requests for this project" box is now ticked:), was easy indeed.

[hakonanes]

Package is now downloadable from conda-forge: https://anaconda.org/conda-forge/morphops. I'll make a PR tomorrow updating the installation guide, and perhaps adding a conda badge to the README?

[vaipatel]

Package is now downloadable from conda-forge: https://anaconda.org/conda-forge/morphops

That's awesome, thanks for driving everything there. Just tested it, works like a charm.

I'll make a PR tomorrow updating the installation guide, and perhaps adding a conda badge to the README?

Sure, that sounds great. Thanks again.

[vaipatel]

First time trying so hope this works: @all-contributors please add @hakonanes for all the superb help with documentation, infrastructure, and maintenance

[allcontributors]

@vaipatel

File README.md was not found in the repository (vaipatel/morphops).

[hakonanes]

Thank you for the kind words :) I had forgotten that rst wasn't supported by allcontributors...

I see that Sphinx doesn't show the contents of CONTRIBUTORS.rst, can this be because an "include" in a file with a "include ../../file" must also be "include ../../file"? I don't know.

[vaipatel]

Yea quite possibly. I was wondering why I couldn't see the Contributors section even when I clicked on just the README_for_docs.rst.. I felt I would have been able to see it there even if sphinx couldn't do the right thing off of the include chain in index.rst.. I'm sure I'm missing something obvious (and very possibly your point).

But I just copied the Contributors section directly to the README_for_docs.rst for now (#20) like you saw.

More broadly, I'm leaning toward doing a separate smaller README.md instead of the autogenerated README.rst some point, hopefully very soon.

[hakonanes]

More broadly, I'm leaning toward doing a separate smaller README.md instead of the autogenerated README.rst some point, hopefully very soon.

Some things will be repeated, but not much, so I think that is fine.