Package: pythontemplatepackage
PythonTemplatePackageA template repo for Python packages featuring:main/devbranch workflowunittests and code coveragepublishing the package on PyPibuilding documentation and publishing via GitHub pagesHow ToTo create a new Python package from this template, start by cloning this repo (or use it as a template when creating a new repo on GitHub) and then follow the procedure outlined below.Badges READMETheREADME.mdis obviously specific to your project, but you might want to use the badges at the top.Thetests,build, anddocbadge show the success status of the respective GitHub actions. The easiest is to follow the procedure below and update them afterwards.Thecodecovbadge should be replaced by the one specific to your package (seeTestsbelow).In thepypibadge the package name needs to be adapted. After the first successful upload (seePyPibelow) it will show the correct version and link to the PyPi page.In thedocbadge, you may want to link to the actual documentation (as is done above) instead of the GitHub action (as is the default).Package NameThe example package provided by this repo is namedpythontemplatepackageand this name appears in many locations. Therefore, the first step is to choose a package name (check that it is available on PyPi if you plan to publish it there!) and replace all occurrences by the name of your package. In particular, you have to rename the folderpythontemplatepackageaccordingly and replace all occurrences in the following files (this is described in more detail in the respective sections below):setup.pytests/test_template.py.github/workflows/tests.yml.github/workflows/test_dev.ymldoc/conf.pydoc/index.rstdoc/api_summary.rstFolder StructureYour source code goes into thepythontemplatepackagedirectory (after renaming it to your package name).Your unittests go into thetestdirectory.Your documentation goes into thedocdirectory.The.github/workflowsfolder contains*.ymlfiles that define GitHub actions thatrun tests on themainanddevbranch (seeTests)publish the package onpypi.org(seePyPi)build the documentation and publish it via GitHub pages (seeDocumentation)Adaptrequirements.txtandsetup.pyList all required Python packages inrequirements.txt.Insetup.pyreplace the following:name="pythontemplatepackage": replace with the name of your packageversion="...": the version of your packageauthor="...": your nameauthor_email="...": your emaildescription="...": a short description of the packageurl="...": the URL of the repopython_requires="...": the Python version requirement for your packageMoreover, in theclassifiersargument, you may want to adapt the following to your liking:Programming Language :: Python :: 3License :: OSI Approved :: GNU General Public License v3 (GPLv3)Operating System :: OS IndependentIf you change the license information, you probably also want to adapt theLICENSEfile and the badge at the top of theREADME.md.TestsReplace thetest_template.pyfile with some real tests for you package (at least, you have to replacepythontemplatepackagewith your package name for things to work).Intests.yml(formainbranch) andtest_dev.yml(fordevbranch) adapt the following:os: [ubuntu-latest, macos-latest, windows-latest]: operating systems to test forpython-version: ["3.9", "3.10"]: Python versions to test forpythontemplatepackage: the name of your package chosen aboveUpload coverage to Codecov: you can delete this section if you do not want to usecodecov.io(remember to also remove the codecov badge above)If you use codecov, you will have to:enable the project in your accountadd theCODECOV_TOKENto your repository's action secrets to be able to upload reportsget the correct coverage badge after the first report has been uploaded underSettings > Badges & Graphs(the link includes a token).The GitHub actions for running tests on themainanddevbranch are almost identical. The only differences are:their name (used to display in the web interface)the branch name (adapt if you use different names)tests onmainalso upload code coverage reportsthe test and codecov badge refer the tests onmainThe tests run onpushandpull_requestevents of the respective branch or when triggered manually.PyPiYou have to set up an API token to be able to upload to PyPi:In youPyPi account pagecreate a new API token valid for all projects (will be changed later).In the repository's GitHub page underSettings > Secrets > Actionscreate a newRepository Secretwith namePYPI_API_TOKENand copy-paste the PyPi token (pypi-...).Afterthe  first successful upload,changethat token by one that is specific to this package (for security reasons).DocumentationThedocfolder contains a skeleton documentation using theRead the Docs Sphinx Themethat you can adapt to your needs. You should replace the following:inconf.py,index.rst,api_summary.rstreplacepythontemplatepackagewith your package nameinconf.pyadapt the following:project = 'pythontemplatepackage'copyright = '...'author = '...'Local BuildsFor local builds, you can runmakecommands in thedocdirectory (you will have to install the packages specified indoc/requirements.txt), in particularmake html: builds the documentationmake doctest: runs all code examples in the documentation and checks if the actual output matches the one shown in the documentationmake clean: remove all built files (including_autosummaryandauto_examples)make help: get information about available make commands.Publish via GitHub PagesTo publish the documentation via GitHub pages, you have to:create thegh-pagesbranchenable GitHub pages ongh-pagesbranch using the/(root) directory.Thedocaction builds the documentation viamake htmland pushes it to thegh-pagesbranch. It also runsmake linkcheckandmake doctestto check for missing links and test examples in the documentation.