Dev (#5)

* fix RTD build and update instructions

* fix pre-commit ignore files issue

* use conda environment.yml for RTD build

* add pip install to RTD config

* fix RTD links

* Add more template instructions

* update readme

* don't ingore pickle files

* remove duplicate ipykernel in environment.yml

* use packagename in make env commands

* update contribute guide and readme

* reorganize project urls in pyproject.toml

* miss-spelling

Author: mdtanker

.gitignore

@@ -2,9 +2,6 @@
 data/*
 !data/.gitkeep
 
-# Ignore any generated pickle files
-**.pickle
-
 # Ignore the virtual environment
 **uv.lock
 

CONTRIBUTING.md

@@ -164,7 +164,7 @@ git remote add upstream https://github.com/organizationname/samplepackagenamee.g
 ### Setting up `nox`
 
 Most of the commands used in the development of `samplepackagename` use the tool `nox`.
-The `nox` commands are defined in the file [`noxfile.py`](https://github.com/organizationname/samplepackagename/blob/main/Makefile), and are run in the terminal / command prompt with the format ```nox -s <<command name>>```.
+The `nox` commands are defined in the file [`noxfile.py`](https://github.com/organizationname/samplepackagename/blob/main/noxfile.py), and are run in the terminal / command prompt with the format ```nox -s <<command name>>```.
 
 You can install nox with `pip install nox`.
 
@@ -207,6 +207,8 @@ We use [pre-commit](https://pre-commit.com/) to check code style. This can be us
 nox -s lint
 ```
 
+To have `pre-commit` run automatically on commits, install it with `pre-commit install`
+
 Go through the output of this and try to change the code based on the errors. Search the error codes on the [Ruff documentation](https://docs.astral.sh/ruff/), which should give suggestions. Re-run the check to see if you've fixed it. Somethings can't be resolved (unsplittable urls longer than the line length). For these, add `# noqa: []` at the end of the line and the check will ignore it. Inside the square brackets add the specific error code you want to ignore.
 
 We also use [Pylint](https://pylint.readthedocs.io/en/latest/), which performs static-linting on the code. This checks the code and catches many common bugs and errors, without running any of the code. This check is slightly slower the the `Ruff` check. Run it with the following:

Makefile

@@ -1,4 +1,3 @@
-# Build, package, test, and clean
 PROJECT=samplepackagename
 
 ####
@@ -8,13 +7,13 @@ PROJECT=samplepackagename
 ####
 
 create:
-	mamba env create --file environment.yml
+	mamba env create --file environment.yml --name $(PROJECT)
 
 install:
 	pip install --no-deps -e .
 
 update:
-	mamba env update --file environment.yml --prune
+	mamba env update --file environment.yml --name $(PROJECT) --prune
 
 remove:
 	mamba env remove --name $(PROJECT)

README.md

@@ -20,16 +20,20 @@ Steps:
     - choose public or private. This can be changed later, but to be published on PyPI or Conda-Forge, or for the documentation website to work, it needs to be public.
     - create the repository
     - update any repository settings, below are my recommended settings:
-        - protect the main branch so any changed to it need to be made through a Pull Request.
+        - enable discussions
+        - only allow squash merging (disable the other options)
+        - always suggest updating pull request branches
+        - automatically delete head branches
+        - protect the main branch so any changes to it need to be made through a Pull Request.
             - go to the repository's `Settings`, `Branches`, `Add branch ruleset`. Name it "protected_main", make the `Enforecement status` Active, include the Default branch as the target, and check the following `Rules`: `Restrict deletion`, `Require a pull request before merging`, only allow `Squash` as a merge method, and `Block force pushes`
 2) Update this template:
-    - clone your repository to your computer with `git clone <url of the github repo>`
-    - change all instances of `samplepackagename` in this repository with your chosen name. (If use a program like VSCode use a `search and replace` function (i.e. `ctrl+f`))
+    - clone your repository to your computer with `git clone <url of the github repo>`; if you create the repository on an organization's GitHub instead of your personal one, first fork the repository before you clone it.
+    - change all instances of `samplepackagename` in this repository with your chosen name. (If use a program like VSCode use a `search and replace` function (i.e. `ctrl+f`)), there should be over 100 instances of `samplepackagename`.
         - this includes the folder name of `src/samplepackagename/`
     - replace all instances of `yourname` with your name
         - your name can be "Maintainers of <samplepackagename>" if there are multiple people.
-    - replace all instances of `organizationname` with your GitHub organization (or personal) account name.
-    - update `pyproject.yml` with a description and keywords
+    - replace all instances of `organizationname` with your GitHub organization (or personal) account name, whichever is going to host the repository.
+    - update `pyproject.yml` with a description (1 sentence) and keywords ()
     - add a description of your project here in the README, as well as in `docs/index.md`.
     - add your info to `AUTHORS.md`
     - at this point, it might be good to make your initial commit to your repository with the following git commands:
@@ -39,9 +43,10 @@ Steps:
         git commit -m "initialize template with names"
         git push -u origin new-branch
         ```
-    - in your GitHub repository, go to the `Pull request` tab and open a PR for your changes. Merge this into main.
+    - in the GitHub repository, go to the `Pull request` tab and open a PR for your changes. Merge this into main.
 3) Add your code
-    - pull in your above changes with `git fetch` and `git pull`.
+    - pull in your above changes with `git checkout main` and `git merge upstream/main`
+    - if your working off a fork: push the above commit to sync your fork with upstream with `git push origin main`.
     - decide on a module name(s)
         - these need to be lowercase, should be short and while possible, shouldn't include underscores.
         - if your package is going to be small, a single module with the same name as the package is fine. If it's going to be more than a few hundred lines of code, it's best to separate your code into distinct modules which perform similar tasks. - for each module you want do the following:
@@ -73,7 +78,7 @@ Steps:
 5) Create environment, style check, test, and commit your changes.
     - follow the instructions in `CONTRIBUTING.md` starting at section `Setting up nox` and stopping before `Publish a new release`.
     - these steps should result in a merged PR with your code.
-6) Set up automated Zenodo releases
+6) Set up automated Zenodo releases (only for Public repositories)
     - if you haven't already, link your organization (or personal) GitHub account to [Zenodo](https://zenodo.org/) using `Linked accounts` under your Zenodo profile.
     - do to the `GitHub` menu on your Zenodo profile.
     - click the Sync button and then turn on the switch for your repository.

environment.yml

@@ -18,7 +18,6 @@ dependencies:
   - nbsphinx
   - ipykernel
   # dev
-  - ipykernel
   - jupyterlab
   # below packages need to be installed with pip (aren't available in conda-forge)
   # - pip

pyproject.toml

@@ -33,13 +33,6 @@ dynamic = ["version"]
 dependencies = [
 ]
 
-[project.urls]
-Homepage = "https://github.com/organizationname/samplepackagename"
-"Bug Tracker" = "https://github.com/organizationname/samplepackagename/issues"
-Discussions = "https://github.com/organizationname/samplepackagename/discussions"
-Changelog = "https://github.com/organizationname/samplepackagename/docs/changelog.md"
-
-
 [dependency-groups]
 test = [
   "pytest >=6",
@@ -63,6 +56,12 @@ all = [
   {include-group = "docs"},
 ]
 
+[project.urls]
+Homepage = "https://github.com/organizationname/samplepackagename"
+"Bug Tracker" = "https://github.com/organizationname/samplepackagename/issues"
+Discussions = "https://github.com/organizationname/samplepackagename/discussions"
+Changelog = "https://github.com/organizationname/samplepackagename/docs/changelog.md"
+
 
 [tool.hatch]
 version.source = "vcs"