GitHub actions to work with sphinx docs and conda packages

[dprada]

Hi! Our lab is recently working with your cookie-cutter to begin every new project. Thanks for the initiative and the work to keep it operative and well documented.

We'd like to suggest the inclusion of two GitHub actions that might be useful for most of the users. We missed the automatization of the two following workflows:

• The sphinx HTML documentation creation and its pushing to a gh-pages to be served by GitHub pages.
• The production of new conda packages with new releases and pre-releases, and their upload to Anaconda.

Because of this reason, we developed, based on other public actions, two actions to cover these needs: https://github.com/uibcdf/action-sphinx-docs-to-gh-pages
https://github.com/uibcdf/action-build-and-upload-conda-packages

I am not sure if every user of this cookie-cutter would found these useful. Maybe not, what's your opinion? If you think that these workflows can be helpful to other colleagues. Please, feel free to copy or re-cook the scripts to be included here. No problem. Maybe MolSSI could have their own GitHub actions.

Thanks again for offering this tool to the community.

[Lnaden]

Thanks for the suggestion and glad you are finding the cookiecutter helpful. Im reluctant to add these two items to the cookiecutter directly for a couple reasons:

• I'm worried about scope creep
• Not everyone is going to want to use Sphinx or GitHub Pages explicitly or at all
• Conda package building and deploying is a world in and of itself.

I do like both options personally and would find uses for them in various projects, but I don't know if we should add them to this explicit cookiecutter as "recommended" items.

While true, we do have some default Sphinx files, we don't actually do anything for building and publishing because there can be a fair amount of nuance with Sphinx, especially as versions change and potentially break plugins (a nightmare I have had to chase down a few times in some projects)

Conda building is something I don't think is straightforward enough to give a broad recommendation for conda-build on its own. Our README even explicitly advises against conda-build unless you know what you are doing in favor of conda env for testing and Conda Forge for deployment. Given the complexity of what is going on under the hood of that GHA you recommended, I think it may cause more confusion than it solves when an issue arises.

With all that said, it may be worth adding documentation and options in the central or nested READMEs to make suggestions on how people can interface with these tools. I'm also open to counter arguments, especially on the Conda side of things, its just going to take a very strong case for me to be comfortable with pointing people directly at conda-build.

[dprada]

Thanks for your clear and kind answer. I understand and share your opinions. And I don't have any strong counter arguments to enrich the discussion. One thing is everyone's personal preferences to implement in their repositories (most of them are based on "this is what worked for me up to now"). And another thing is keeping a cookie-cutter clean and higienized... and useful for everybody, as you do.

Thanks again for your feedback. We really appreciate it, as we strongly appreciate the MolSSI efforts to show us the best practices to develop and maintain our tools. We are learning a lot little by little with your materials.

[jchodera]

@Lnaden I just wanted to revive this issue, since I'm 100% in agreement with @dprada that this would be super useful. It's so easy to publish with GitHub Pages that automating docs builds with GitHub Actions is the "killer app" in making it truly easy for users to just edit a couple of files and have useful docs (including API docs!) appear online.

Making it easy for users to add and maintain useful documentation isn't scope creep here---it's an essential part of software development. If you software doesn't have documentation, it means you don't want or care about other people using it. We want to incentivize users to do the right thing, and the best way to do that is to make the barrier to doing so near zero.

It doesn't necessarily have to be sphinx---#192 also suggests MkDocs as a simpler alternative. But having at least one of these mechanisms automatically build and publish docs via GitHub Actions seems like exactly what is needed to make sure every project has dead-simple high quality online docs available.

[mikemhenry]

Will the search still work if it is on github pages? readthedocs does some fancy indexing to make the search fast and useful https://docs.readthedocs.io/en/stable/development/search.html they do have all the code open source and there is a self-hosting option for Elasticsearch if you don't want to pay for the SaaS