Next Steps¶
Once you have rendered your package and set it up on GitHub you may wish to enable Travis CI and Read the Docs. Configuration for these services is included in the template, and while their use is optional, it is recommended.
Setting Up Continuous Integration¶
Continuous Integration (CI) services continuously test your package for each commit. Every pull request against your main repository will be automatically tested and failing tests will be flagged by these services.
GitHub Actions¶
GitHub now provides an integrated CI service called GitHub Actions.
The default workflows in .github/workflows
show how to set up integration testing
upon every push or pull request, ci_tests.yml
, and how to run scheduled tests via cron, ci_cron_weekly.yml
.
The default ci_tests.yml
file contains a large number of builds against various versions of Python, astropy, and
numpy, and you should choose the ones relevant to your project. Generally, you should aim to always have your
main
branch work with the latest stable and latest development version of astropy (i.e., the
astropy git master branch) and the same versions of python and numpy supported
by astropy. The template ci_tests.yml
covers those versions; in some
circumstances you may need to limit the versions your package covers.
Codecov¶
Codecov is a web interface to monitoring what lines of code in your project are executed by your test suite.
If you register your package with codecov.io, you
will need to uncomment the codecov section in the ci_tests.yml
file under
.github/workflows
to enable upload of your coverage statistics to codecov.
Read the Docs¶
In addition to testing the code, it is often useful to build documentation continuously as the code is developed. Read the Docs is a web site that provides exactly this service. If you want the documentation for your project to be hosted by Read the Docs, then you need to setup an account there. The following entries in “Advanced Settings” for your package on Read the Docs should work:
Select
Install your project inside a virtualenv using setup.py install
Edit
.rtd-environment.yml
with your package requirements (this file is used by conda on RTD to install the requirements for your package).Activate
Give the virtual environment access to the global site-packages dir.
All other settings can stay on their default value.
Customizing the package¶
Once you have run cookiecutter you can edit the files in the folder to further customize your package. This section of the documentation lists some ways you might want to do this.
Customizing the package metadata¶
All of the metadata about the package (name, version, keywords, etc.) are
defined in the setup.cfg
file. This is described in detail in the
setuptools documentation.
Customizing the documentation CSS¶
As described in the documentation configuration file (template/docs/conf.py), the documentation uses a custom theme based on bootstrap. You can swap out this theme by editing the configuration file. You can also tweak aspects of the documentation theme by creating a custom CSS file in your package documentation.
To do this, create a new CSS file in <packagename>/_static/
– let’s call it
<packagename>.css
:
cd <packagename>/_static/
touch <packagename>.css
We’re going to set the HTML style to this new <packagename>.css
stylesheet,
so we need to import the original bootstrap-astropy
style before we start
modifying entries. To the first line of your <packagename>.css
file, import
the default style. We can add any custom CSS below the import. For example, to
hide the Astropy logo and Astropy link from your project’s documentation menu
bar:
@import url("bootstrap-astropy.css");
div.topbar a.brand {
background: none;
background-image: none;
}
div.topbar ul li a.homelink {
background: none;
background-image: none;
}
We now have to include the <packagename>.css
in the documentation, and tell
Sphinx to use the new style. To do this, edit your
<packagename>/docs/conf.py
file and add the lines:
# Static files to copy after template files
html_static_path = ['_static']
html_style = '<packagename>.css'