In this tutorial, we will walk through using the Research Software Encyclopedia (rse) with criteria hosted here to generate a static interface to display your research software.
If you are faculty, student, or some research staff that maintains a set of software, you might want to have a place to share this set, meaning a version controlled record (GitHub repository) and web interfaces to interact with it.
You can first install the rse software with pip:
pip install rse[all]
We choose to install “all” so that dependencies for generating a web interface are included.
Next, cd into a folder that you intend to create as a GitHub repository. For example, I’m going to call mine “software”:
mkdir software cd software git init
And of course you’ll need to follow standard instructions for creating a new repo.
You can then initialize a new research software database.
$ rse init INFO:rse.main.config:Generating configuration file rse.ini INFO:rse.main:Database: filesystem
It will create an
rse.ini configuration file in your folder! This is a fairly
simple configuration file that just keeps track of your database preferences.
Let’s add software repos to our database! You can either add via one off commands:
rse add github.com/singularityhub/sregistry INFO:rse.main.database.filesystem:github/singularityhub/sregistry was added to the the database.
Or you can import from a file with a single list of repository names:
# repos.txt github.com/singularityhub/sregistry github.com/singularityhub/singularity-compose github.com/singularityhub/singularity-cli github.com/singularityhub/singularity-docker
$ rse add --file repos.txt INFO:rse.main:Database: filesystem INFO:rse.main.database.filesystem:github/singularityhub/singularity-compose was added to the the database. INFO:rse.main.database.filesystem:github/singularityhub/singularity-cli was added to the the database. INFO:rse.main.database.filesystem:github/singularityhub/singularity-docker was added to the the database.
Notice that the previously added repository “singularityhub/sregistry” was not added again. If you inspect your file system, you’ll notice that we now have folders and metadata files for each repository added.
$ tree database/ database/ └── github └── singularityhub ├── singularity-cli │ └── metadata.json ├── singularity-compose │ └── metadata.json ├── singularity-docker │ └── metadata.json └── sregistry └── metadata.json
At this point you can further interact with your software database via any of the commands. You might also be interested in local and bulk annotation of your software. You probably (minimally) want to add the files to git and push to your remote.
More likely you want a fun interface for others to explore your software. You can generate that, perhaps in a subfolder called “docs” to generate on GitHub pages. If your repository name is “software,” you would need to first export a URL prefix, along with the GitHub address that you intend to serve it from:
export RSE_URL_PREFIX=/software-example export RSE_ISSUE_ENDPOINT=https://github.com/rseng/software-example $ rse export --type static-web docs/
This again generates all the static files you’d need for your GitHub pages, and the issue endpoint will be available if you want others to be able to add annotations via issues.
$ tree docs/ docs/ ├── api │ ├── criteria │ │ └── index.json │ ├── repos │ │ └── index.json │ └── taxonomy │ └── index.json ├── data.json ├── index.html ├── repository │ └── github │ └── singularityhub │ ├── singularity-cli │ │ ├── annotate-criteria │ │ │ └── index.html │ │ ├── annotate-taxonomy │ │ │ └── index.html │ │ └── index.html │ ├── singularity-compose │ │ ├── annotate-criteria │ │ │ └── index.html │ │ ├── annotate-taxonomy │ │ │ └── index.html │ │ └── index.html │ ├── singularity-docker │ │ ├── annotate-criteria │ │ │ └── index.html │ │ ├── annotate-taxonomy │ │ │ └── index.html │ │ └── index.html │ └── sregistry │ ├── annotate-criteria │ │ └── index.html │ ├── annotate-taxonomy │ │ └── index.html │ └── index.html └── static └── css └── style.css 21 directories, 18 files
The interface portal is shown at the top of the post! From there you can see criteria and taxonomy items defined when you generated the interface, along with your list of software. For each, you can click on the owl (🦉️) to annotate for taxonomy categories, or the check (✔️) to annotate for criteria. Here is annotating for the criteria:
And here is for annotating for the taxonomy:
Continue reading to see how these interfaces can trigger an automated workflow to annotate your database.
If you add a set of templates and a GitHub workflow that knows how to parse them into pull requests that will annotate the software, your static web interface becomes an annotation interface! Specifically, you will need these files:
mkdir -p .github/workflows .github/ISSUE_TEMPLATE cd .github/ISSUE_TEMPLATE wget https://raw.githubusercontent.com/rseng/software/master/.github/ISSUE_TEMPLATE/annotate-criteria.md wget https://raw.githubusercontent.com/rseng/software/master/.github/ISSUE_TEMPLATE/annotate-taxonomy.md cd ../workflows wget https://raw.githubusercontent.com/rseng/software/master/.github/workflows/issue-annotation.yml
After these templates are added, when a visitor clicks submit on your interface served on GitHub pages, it will open an issue that (when posted) will trigger a workflow to open a pull request and complete the annotation on behalf of the user’s username. Here are example issues generated:
And the subsequent pull requests generated! You can see both at rseng/software-example.
And any user can open an issue using your template to accomplish the same. Cool!
At this point you can commit files, push, and go into your repository settings to enable GitHub pages. You can share the base url with others, or even just one repository on social media to ask for annotations. By the way, we encourage you to add your software to the rseng/software database. If you have any other ideas or suggestions for this tool, please open an issue there or on the research software encyclopedia. If you want to discuss or work on specific criteria or the taxonomy, then you can do that here.