Package: tabularasa
Template Github RepositoryThis is a template repository for python projects which use sphinx for
documentation, github actions for building, pytest and codecov for test
coverage.Getting StartedChoose a name for the new repository. Make sure it's available as a name ontestPyPiandPyPi. Create a new directory with that chosen module name.Create a new repository on github by clicking "Use this template"Clone this repository into your new directorygit clone https://github.com/edmundsj/<MODULE_NAME>.git <MODULE_NAME>Set github pages to use thedocs/folder for github pages at the bottom of the "Settings" pageAdd this repositry to codecov:https://app.codecov.io/gh/edmundsj, and add the CODECOV_TOKEN secret to the github repository. You may need to login to codecov to refresh the repositories.Create a new authentication token on testPyPi and add it as a github secret namedtest_pypi_token*Create a new authentication token on PyPi and add it as a github secret namedpypi_token*Navigate into the cloned repository, and run the setup script. This will change all the names in the relevant setup files. If this does not work, see the end of the tutorial.:python repo_setup.pyIf desired, once the build on the remote server finishes, replace the tokens from testPyPi and pyPi with ones that are restricted to this pyPi project. Delete the old ones.Create a status badge from the '... -> Create Status Badge' in the github actions area separately for docs and build, and paste them in the README, as well as from codecov. Add a project description in "SETUP.py" and fill out the sections of the downloaded README.Done! Your repository should be viewable on github pages:https://edmundsj.github.io/REPO_NAME/, and your code coverage should be available on codecov.ioNote - since the package does not already exist on pyPi or testPyPi you will need to create a token that has access to all your projects. This obviously isn't an optimal way of doing things, and this should really be changed. I may want to add a setup script which does all the renaming, changes github hooks, and does an initial deploy to pypi and testpypi. If you want after the first push, you can create a new token restricted to the newly-pushed project.If step 6 does not work, you may need to do a git pull before execution. If that doesn't work, you can execute the following manually:6a. Change the git hooks location:```git config core.hooksPath .hooks```6b. Change this repository's name withgit remote set-url origin <NEW_REPO_URL>6c. In thesetup.py,.hooks/pre-commit, and.github/workflows/python-package-condafiles, change all instances of "pytemplate" to "MODULE_NAME".6d. Push to the new repository```git push -u origin main```FeaturesGithub actions unit test integration via pytestGithub actions package management with condaGithub actions documentation build using sphinx and reST/markdown, with auto
self-push to repository after successful buildGithub pages documentation hosting/integrationLocal commits hooks run full test suiteCoverage uploaded automatically to codecov after successful build[FUTURE] Auto-deploy to pyPi/testpyPi after successful buildCommon IssuesRe-running builds on github actions will cause them to fail, as the build number deployed to PyPi depends on the github run number, which does not change if you restart a build.Pypi deploy is a little slower than test pypi, so it may not always be downloading the latest version.How to UseAdding Additional Unit TestsAny time you want to add additional unit tests just add them to those in thetests/directory and prepend with the nametest. These will be
automatically found by pytest and run during local commits and remote builds.Writing the DocumentationThe documentation source is located indocs/sourceand is written in
restructured text (markdown is also available).Building the DocumentationSimply runmake htmlfrom thedocs/directory. This will compile the
files in thedocs/source/directory, and place them in the maindocs/directory where github pages can find them.Dependencies / Technologies UsedSphinxpytestGithub ActionsCodecovGithub PagesAcknowledgementsThanks to all the great people on stack overflow and github, for their
seemingly boundless tolerance to my and others' questions.