Document python package development process (#24)

* Document ability to override error handling of R CMD check

* Document development process

* Document development process

Author: alecw

.github/workflows/R-reusable.yml

@@ -69,4 +69,5 @@ jobs:
           working-directory: R/bican.mccarroll.${{ inputs.package_name }}
           upload-snapshots: true
           build_args: 'c("--no-manual","--compact-vignettes=gs+qpdf")'
+          # for some reason this needs to be quoted lest it gets passed as (error)
           error-on: ${{ format('"{0}"', inputs.error-on) }}

R/README.md

@@ -3,7 +3,7 @@ How to create an R package for the bican-mccarroll-manuscript1 repository.
 
 ## Creating a package using RStudio
 
-1. Get started with github and create a branch using the [basic github workflow](https://docs.google.com/document/d/1A5T8ZVhNxP0GCQmmo1R8qaPPXah9cvSLI96U3TZdYos/edit?tab=t.0) 
+1. Get started with github by cloning the broadinstitute/bican-mccarroll-manuscript1 repository and creating a branch using the [basic github workflow](https://docs.google.com/document/d/1A5T8ZVhNxP0GCQmmo1R8qaPPXah9cvSLI96U3TZdYos/edit?tab=t.0) 
 1. In RStudio, go to `File` -> `New Project...`
 1. Pick `New Directory`
 1. Pick `R Package`
@@ -14,13 +14,27 @@ How to create an R package for the bican-mccarroll-manuscript1 repository.
    - `cp .github/workflow-templates/roxygen.yml .github/workflows/roxygen-frob.yml`
 1. Edit these two files and replace `<package_name>` with your package name
 1. Do your package development as usual, including adding documentation using roxygen2.
+1. Create a `README.md` file in the root of your package.  You can copy the one in R/bican.mccarroll.helloworld/ and modify it as appropriate.
 1. When you are ready to commit your changes, use the [basic github workflow](https://docs.google.com/document/d/1A5T8ZVhNxP0GCQmmo1R8qaPPXah9cvSLI96U3TZdYos/edit?tab=t.0) to commit and push your changes.
 
 Note that for now we are requiring review before PRs.  We can change if this is cumbersome.
 
 Note also that the github actions are not active until they are merged into the main branch, so they won't run 
 until they have been merged.  Subsequent PRs will trigger the R cmd check action.
 
+## Handling less-than-perfect R CMD check results in continuous integration
+Ideally your package will pass R CMD check with no errors or warnings, but if that is not possible,
+you can set the `error_on` parameter of rcmdcheck in R-frob.yml like this:
+```yaml
+jobs:
+  call-R-reusable:
+    uses: ./.github/workflows/R-reusable.yml
+    with:
+      package_name: helloworld
+      error-on: 'error' # don't fail if warnings or notes are present
+    secrets: inherit
+```
+
 ## Generating documentation via github actions
 You can cause roxygen2 to run via github action by creating a PR, and then commenting on the PR
 with `/document.<package_name>`, e.g. `/document.frob`.  This will trigger the roxygen action, which will generate the 

python/README.md

@@ -0,0 +1,19 @@
+# Creating a Python package
+How to create a Python package for the bican-mccarroll-manuscript1 repository.
+## Creating a package using PyCharm
+1. Get started with GitHub by cloning the broadinstitute/bican-mccarroll-manuscript1 repository and creating a branch using the [basic GitHub workflow](https://docs.google.com/document/d/1A5T8ZVhNxP0GCQmmo1R8qaPPXah9cvSLI96U3TZdYos/edit?tab=t.0).
+1. In PyCharm, go to `File` -> `New Project...`.
+1. Set the location of the project to `<your-git-sandbox>/bican-mccarroll-manuscript1/python/bican_mccarroll_<your-package-name>`, where `<your-package-name>` is the name of your package.
+1. I picked the following settings, which I'm not sure are the best:
+   - Interpreter type: `Custom environment`
+   - Environment: `Generate new`
+   - Type: `Virtualenv`
+   - Base python: `Python 3.9.6`
+1. Click `Create`.
+1. In the project view, create directories `src` and `tests` under the project root.
+1. Right-click the `src` directory and select `New` -> `Python Package`. Name it `bican_mccarroll_<your_package_name>`.
+1. Go to Settings -> Project -> Project Structure, and label 'src' and 'tests' as Sources and Tests, respectively.
+1. Develop your package as usual, including unit tests as appropriate.
+1. Put a `LICENSE` file in the root of your package, and a `README.md` file in the root of your package.  You can copy the ones in python/bican_mccarroll_helloworld/ and modify the README.md as appropriate.
+1. Create a `pyproject.toml` file in the root of your package.  You can copy the one in python/bican_mccarroll_helloworld/ and modify it as appropriate.
+1. When you are ready to commit your changes, use the [basic github workflow](https://docs.google.com/document/d/1A5T8ZVhNxP0GCQmmo1R8qaPPXah9cvSLI96U3TZdYos/edit?tab=t.0) to commit and push your changes.