Package: py-qs-example
pypi-sphinx-quickstartOverviewThis repo is a template to use for starting a new Python package
which is hosted on PyPi and uses Sphinx for documentation
hosted on Github pages. It has a built-in CI/CD system using Github Actions,
all you need to do for that is hook up the secrets. The CI system has
the following features:Runs any tests intestswithpytestLints code usingflake8Static code checks withmypyDeploys PyPI packageDeploys Sphinx documentation on Github PagesAutodoc/autosummary already set upAutomatic sitemap.xml generatedJust add Google Analytics ID to enable trackingRead the Docs Theme with Custom CSSNotebook-style examples with Sphinx Gallery complete with download and Binder linksAuto-converts Jupyter notebooks innbexamplesAuto-merges pull requests by maintainersAuto-drafts release notes based on merged pull requestsSyncs new changes from the cookiecutter template usingcrufton a cron workflow. Creates a PR with the changes to be merged
manually. Creates an issue if it is not possible to commit the changes (when there are
changes to workflow files).Collects TODO comments and converts them into issues (optional)Closes TODO issues once comments are removed (optional)Getting StartedRequired StepsFollow the steps in one of the two ways to start, then the following steps.Two Ways to StartCookiecutterThis template is available as acookiecutter.
Findthe cookiecutter for this template here.
This is the recommended way to get started if you are already familiar with how
everything works. No example files will be included.Repo TemplateClick the "Use this template" button at the top of the repo page, then
fill out the name and description your new repo. This is the recommended way to get
started if you are figuring out how everything works as it gives you a fully
working demo with example files.Adding SecretsGo into the repo settings, under Secrets, and add the following secrets:pypi_password: Personal token for PyPIgh_token: Github personal access tokenCODECOV_TOKEN(optional):codecov.iotoken for this projectTODO_ACTIONS_MONGO_URL(optional): MongoDB connection url, complete with
username and password. SeeSetup MongoDB.conf.pyEditconf.pyin the main repo directory. This contains the main
settings for the PyPi package. If you used the repo template, you will need to change
all the settings. Otherwise, thecookiecutterwill have filled out most of the settings,
but specific package details such as dependencies
still need to be added.Adding Project SourceDelete the folderpy_qs_example, and add your own package
with the name you set inconf.PACKAGE_NAME.Adding Global Requirements to BuildIf you do not already havepipenvinstalled, you will need to run:pip install pipenvThen regardless of whether you already hadpipenvinstalled, you will
need to navigate to the repo folder and run:pipenv updateSetting up DocumentationIf you used the repo template, editdocsrc/Makefileto changeSPHINXPROJto set it to the name
you set inconf.PACKAGE_NAME(withcookiecutterthis step is not necessary.)Editdocsrc/source/index.rstto remove the example included files. Replace
with your own if you wish or entirely delete the My Module and
My Package sections if don't wish to use the autosummary directive.Editdocsrc/source/tutorial.rstto put your own tutorial, or remove it
and remove it from thetoctreedirective indocsrc/source/index.rst.You may further modify Sphinx configuration indocsrc/source/conf.pyif you wish.AddSphinx Galleryexamples
in theexamplesfolder. You can also add Jupyter notebook examples in thenbexamplesfolder, and they will automatically be converted to
Sphinx Gallery-style examples and included withexamplesin the
build of the documentation.Adding LabelsThe following labels are used in the CI/CD. They should be added in Labels in the
repo settings:no auto merge: added to prevent automatic merging of
pull requests by maintainersmaintenance: one of the output categories for release notesautomated pr: Used by automated template update cron workflow which
usescruftto check for changes in the template and opens a PR
automatically if so.automated issue: Due to limitations in Github Actions, the template update
cron workflow is not able to commit to the repo if the changes include changes to
workflow files. It instead raises an issue to update the template in this case. This
label is applied to these issues as well as themaintenancelabel.Commit and PushAfter the preceding steps, now commit your changes and push tomasterif not done already. After a few minutes, Github Actions should create
agh-pagesbranch which has the documentation HTML in it.Github Pages SetupNote: This should happen automatically after Github Actions creates
thegh-pagesbranch. But follow these steps if your docs still do
not work.Go to repo settings, Github Pages section. For the Source dropdown,
select "gh-pages branch". The settings page should reload,
and in the Github Pages section it should show the URL of your
documentation. You should be able to see the documentation at the URL
after a few seconds, but it will still be the example documentation.If "gh-pages branch" is not shown in the dropdown, you need to make one
release commit and push it, so that thegh-pagesbranch will be added
to your repo. After doing that, you can go into the repo settings
and select "gh-pages branch" as described.Optional StepsSet Master to Protected BranchIt is recommended to make master a protected branch so that nobody can
delete it.Setup CodecovGo tocodecov.io, log in via Github, click Repositories then
"Add new repository" and select this repository from the list. Copy the
token for Codecov to use in the next step.Setup MongoDB (optional, for TODO integration)For the TODO integration to work, you need a MongoDB instance. You can
get one for free atmlab.com. After creating the database,
create a database user. The MLab interface will show you the format
of the connection url string, which you will fill in the database user's
username and password and use that as theTODO_ACTIONS_MONGO_URLsecret,
as theAdding Secretssection shows.Built-in CI/CDOn Every PushGithub Actions are used to automatically run the following steps on every push:Check Python syntax withflake8RunpytestStatic typing checks withmypyWhen Branch ismasterIf the branch is themasterbranch, then it will also:Uploadpytestresults tocodecovIf there is a change indocsrcIf the branch is the master branch, and there was a change indocsrc, it will do
all the steps in On Every Push and When Branch ismaster, then it will:Build documentation HTML using SphinxCreategh-pagesbranch and copy HTML therePush togh-pagesbranch, which will update the hosted documentationIf there is a change in the package versionIf the branch is the master branch, and there was a change in the package version
inconf.py, it will do
all the steps in On Every Push and When Branch ismaster, then it will:Build documentation HTML using SphinxCreategh-pagesbranch and copy HTML therePush togh-pagesbranch, which will update the hosted documentationBuild Python packageUpload Python package to PyPIIf a Pull Request is OpenedThe CI/CD system will check whether the pull request was opened by a maintainer
(configured in conf.py). If so, it will auto-merge the pull request after
it has passed CI checks. It will then run the deployment pipeline. To avoid
this auto-merge behavior, add the label "no auto merge" to the pull request.Regular UsageOnce everything is set up, just commit your changes. The built-in
CI/CD will take care of testing, build, and deployment of PyPI package
and documentation. If you use pull requests on Github then it will
show you whether it passes the CI tests.ReleasesIf you want to create Github releases notes for your package, they
will already be drafted, just edit them as desired before posting.Local UsageBuilding the documentation locally makes sense if you are
updating it but don't want to make it live yet. You can view
the HTML files in thedocsfolder via a browser after building them.Building DocumentationNavigate into thedocsrcfolder and run:pipenv run make githubThis should generate documentation HTML in thedocsfolder.Uploading to PyPiNavigate to the repo base folder and run:pipenv run python upload.pyUpdating Build RequirementsThe Github Actions CI/CD usesPipfile.lockto install its
requirements. Runpipenv updatelocally to update thePipfile.lockwith the newest dependencies and push into
themasterbranch to get the dependencies updated
on the CI/CD system.Syncing with thecookiecuttertemplateThere is a built-in workflow which runs daily to check for
updates in thecookiecuttertemplate. If it finds an update,
it will usecruftto apply the update and raise a PR with the
changes. Manually review the changes, adjusting if needed, then
merge the PR to keep updated with the template.LinksSee the examplegenerated documentation here.