Tool for uploading project boards to GitHub
Project description
Tool for uploading project boards on GitHub
The package ghproject
is a tool for uploading project boards to GitHub filled with labelled issues. This has been created to aid project management in research software projects on GitHub.
Possible use cases:
- Create an onboarding project board for new team members
- Create a project board for developing FAIR research software
Navigate to API documentation for more detailed and structured information.
Documentation for users
Installation
The tool can be installed with pip:
pip install ghproject
Using ghproject
requires a GitHub Personal Access Token (PAT), which can be created via your GitHub settings. To prevent hardcoding of any access tokens, it's a best practice to keep your GitHub PAT as a local environment variable. By default, the package will inspect the environment variable GITHUB_TOKEN
for the argument --token
.
To set up the Token called GITHUB_TOKEN
for Windows, execute in a terminal:
setx GITHUB_TOKEN <token>
You might need to restart your terminal/IDE for the changes to take effect.
Usage
The tool can be used both from the command line and from a Python interpretor, e.g. a Jupyter notebook. We take as an example the following use case in which we want to upload a project board with accompanying issues. Issues are generated from markdown files that need to contain a header with the issue title and associated labels (as a list of strings).
---
title: Create FAIR software checklist
labels: ["documentation", "feature"]
---
The issue body is then created from the following markdown text. Examples of issues can be found in the folder /md_files
in the repository.
You can call the module to upload a new project to a GitHub reposotory from the command line. Use to following command to view the help file:
python -m ghproject.upload_project -h
For example, the following command will create the project board "My project" in the repository "my_repository" and add the issues generated from the markdown files in the relative folder "/md_files":
python -m ghproject.upload_project --repo "my_repository" --owner "username" --path "./md_files" --project "My project"
The various functions can also be accessed directly from the GitHubAPI class. Example usage would be:
import os
from ghproject import GitHubAPI
# Setup arguments
repo_name = "my_repository"
repo_owner = "username" # Github user name or organization name
token = os.environ["GITHUB_TOKEN"]
path_issues = "./md_files"
project_name = "My project"
repo = GitHubAPI(repo_name, repo_owner, token)
repo.load_markdown_files(path_issues)
repo.push_project(project_name)
repo.push_issues()
repo.add_issues_to_project(project_name)
Documentation for developers
Installation
I recommend installing the tool inside a conda environment:
git clone https://github.com/mwakok/ghproject.git
cd ghproject
conda env create -f environment.yml
conda activate env_ghproject
pip install -e .[dev]
License
Copyright (c) 2022, Maurits Kok
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ghproject-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ae593d1e8a12b74d1b89d1a37a121ee339d2077077e19caa9f44f28b9e46a104 |
|
MD5 | e9613131cd3551c01284fa092b6ae3d7 |
|
BLAKE2b-256 | 7d04de8a8e3cf32728b644d6aaf35e4c158bab6610e3ff573decb134c9954aec |