Adding READMEs to all directories #584

skeating · 2024-12-24T10:30:27Z

Description

Adds a README to all directories to facilitate easier navigation of the tree
Also adds comments where existing README did not make sense/was confusing
Corrected a few areas that were slightly confusing to read
Note changes to files other than README are from merging the main branch back into this one

Type of change

Please delete options accordingly to the description.

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

Suggested Checklist

I have performed a self-review of my own code.
I have made corresponding changes to the documentation.
My changes generate no new warnings.
I have commented my code, particularly in hard-to-understand areas.
I have passed on my local host device. (see further details at the CONTRIBUTING document)
Make sure your branch is up-to-date with main branch. See CONTRIBUTING for a general example to syncronise your branch with the main branch.
I have requested review to this PR.
I have addressed and marked as resolved all the review comments in my PR.
Finally, I have selected squash and merge

…s-pub

codecov · 2024-12-24T10:31:40Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.61%. Comparing base (dad57db) to head (2a15810).

Additional details and impacted files

@@                   Coverage Diff                   @@
##           sk/joss-publication     #584      +/-   ##
=======================================================
+ Coverage                85.50%   87.61%   +2.11%     
=======================================================
  Files                       72       76       +4     
  Lines                     3235     3505     +270     
=======================================================
+ Hits                      2766     3071     +305     
+ Misses                     469      434      -35

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

skeating · 2025-01-13T10:01:20Z

Note: I have only made changes to README files, but I have imported changing from the main branch so a lot of files appear to have changed

stefpiatek · 2025-01-28T09:26:11Z

Would you mind if I rewrote this branch history just so that we don't get the changes coming up in the review?

tomaroberts

Hi @skeating – thanks for this. Various comments scattered throughout the review – some of them are just general thoughts. I do think the front page README needs an overhaul as a priority, and as I was reviewing the PR I was thinking the documentation should be in something like ReadTheDocs, but obviously that's a fair amount of work.

A couple of questions:

Is there a requirement from JOSS to have a README in every directory?
How did you generate all of the README files and the HTML and Markdown at the bottom of the files?
Do future developers need to update the READMEs manually according to any changes they make?

README.md

tomaroberts · 2025-03-04T16:20:44Z

hasher/README.md


 Save the credentials in `.secrets.env` and a LastPass `Hasher API <environment> secrets` note.

+SK QUESTION: is the reference to Last Pass something that is specific to us or is it a dependency somebody else would need. actually I assume the whole Azure thing is rather how we have chosen to do that rather than a necessity for somebody i.e. they might use a different system for storing their hashes


@stefpiatek – see "SK QUESTION" text.

This is specific to us and how we share passwords in the team, as long as they have their own azure tenancy then they should be fine to manage this with the code as-is

orthanc/orthanc-anon/README.md

orthanc/orthanc-raw/README.md

pixl_export/README.md

tomaroberts · 2025-03-04T17:24:29Z

pixl_export/README.md

 ## Notes

- The height/weight/GCS value is extracted only within a 24 h time window
+- The height/weight/GCS value is extracted only within a 24 h time window  <SK: I assume this refers to what can come out of OMOP   >


Agree – this either needs a fuller explanation or deleting.

Yeah this is outdated and should be removed

tomaroberts · 2025-03-04T17:26:27Z

pixl_imaging/README.md

 instances are retrieved. If the study does not exist locally, the entire study is retrieved from the archive.

-Once the study and all its instances are in `orthanc-raw`, the study is sent to `orthanc-anon` via a C-STORE
+Once the study and all its instances are in `orthanc-raw`, the study is sent to `orthanc-anon` via a C-STORE <SK: Please explain what C-STORE operation>


Suggest specifically calling it a "DICOM C-STORE" operation and linking to some documentation. Could link to the official NEMA DICOM docs, but they are a bit impenetrable, hence link I chose.

Suggested change

Once the study and all its instances are in `orthanc-raw`, the study is sent to `orthanc-anon` via a C-STORE <SK: Please explain what C-STORE operation>

Once the study and all its instances are in `orthanc-raw`, the study is sent to `orthanc-anon` via a [DICOM C-STORE operation](https://www.medicalconnections.co.uk/kb/Basic-DICOM-Operations).

Yeah this looks good

pixl_imaging/alembic/README.md

test/README.md

Co-authored-by: Tom Roberts <[email protected]>

stefpiatek

Sorry this had sat on my list for ages. Still not quite sure about the benefit of a readme listing the files for every directory but maybe we can chat about what we're aiming for with it

stefpiatek · 2025-07-07T08:37:06Z

.github/ISSUE_TEMPLATE/README.md

@@ -0,0 +1,10 @@
+## 'ISSUE_TEMPLATE' Directory Contents
+
+### Files


I'm not too sure about having each of the files listed for each README, feels like something that will get out of date very quickly but having a readme for the point of it and perhaps highlighting key files?

Might be worth chatting about it?

stefpiatek · 2025-07-07T08:37:38Z

bin/linters/README.md

@@ -0,0 +1,16 @@
+A directory that contains the files used for linting.


Suggested change

A directory that contains the files used for linting.

Custom linting

stefpiatek · 2025-07-07T08:40:31Z

hasher/README.md


 Save the credentials in `.secrets.env` and a LastPass `Hasher API <environment> secrets` note.

+SK QUESTION: is the reference to Last Pass something that is specific to us or is it a dependency somebody else would need. actually I assume the whole Azure thing is rather how we have chosen to do that rather than a necessity for somebody i.e. they might use a different system for storing their hashes


This is specific to us and how we share passwords in the team, as long as they have their own azure tenancy then they should be fine to manage this with the code as-is

stefpiatek · 2025-07-07T08:45:09Z

pixl_core/README.md


 The `project_config` module provides the functionality to handle
-[project configurations](../README.md#configure-a-new-project).
+[project configurations](../README.md#configure-a-new-project). <== SK comment I'm not sure this goes to exactly the right place OR the name in the # is misleading


Yeah agreed, this should point to the configs readme

Suggested change

[project configurations](../README.md#configure-a-new-project). <== SK comment I'm not sure this goes to exactly the right place OR the name in the # is misleading

[project configurations](projects/configs/README.md)

stefpiatek · 2025-07-07T08:46:37Z

pixl_dcmd/README.md

   for the appropriate tag scheme using [Kitware Dicom Anonymizer](https://github.com/KitwareMedical/dicom-anonymizer)
   and deletes any tags not mentioned in the tag scheme. The dataset is updated in place.
-     - Will throw a `PixlSkipInstanceError` for any series based on the project config file. Specifically, an error
+     - Will throw a `PixlSkipInstanceError` for any series based on the project config file. {SK: this sentence doesn't quite make sense to me} Specifically, an error


Suggested change

- Will throw a `PixlSkipInstanceError` for any series based on the project config file. {SK: this sentence doesn't quite make sense to me} Specifically, an error

- Will throw a `PixlSkipInstanceError` for any series that should be skipped (based on the project config file). Specifically, an error

stefpiatek · 2025-07-07T08:47:38Z

pixl_dcmd/README.md

 If a `manufacturer_overrides` is defined, it will be used to override the `base` tags, if the
 manufacturer of the DICOM file matches the manufacturer in the `manufacturer_overrides`. Any tags
 in the `manufacturer_overrides` that are not in the `base` will be added to the scheme as well.
+[SK: Between this and the previous read me I'm not sure this is totally clear, is it possible to have a full example of the yml file linked so that base and a manufacturer_overrides make a bit more sense ]


Yeah I think we should just have a readme in the projects/configs directory that talks through all the configuration options. There is a template here https://github.com/SAFEHR-data/PIXL/blob/main/template_config.yaml, perhaps we move this to the projects/configs directory?

stefpiatek · 2025-07-07T08:48:17Z

pixl_export/README.md

 to its destination (eg. FTPS). It also uploads DICOM data to its destination after it has been
 processed by the Imaging API and orthanc(s).
-It no longer accepts messages from rabbitmq.
+It no longer accepts messages from rabbitmq. <SK: Please explain>


Yeah agreed, this is a historical change

stefpiatek · 2025-07-07T08:48:56Z

pixl_export/README.md

 ## Notes

- The height/weight/GCS value is extracted only within a 24 h time window
+- The height/weight/GCS value is extracted only within a 24 h time window  <SK: I assume this refers to what can come out of OMOP   >


Yeah this is outdated and should be removed

stefpiatek · 2025-07-07T08:49:24Z

pixl_imaging/README.md

 instances are retrieved. If the study does not exist locally, the entire study is retrieved from the archive.

-Once the study and all its instances are in `orthanc-raw`, the study is sent to `orthanc-anon` via a C-STORE
+Once the study and all its instances are in `orthanc-raw`, the study is sent to `orthanc-anon` via a C-STORE <SK: Please explain what C-STORE operation>


Yeah this looks good

stefpiatek · 2025-07-07T08:53:52Z

test/README.md

 ### Scripts

-`./scripts` contains bash and Python scripts to check the individual components of the system test.
+`../scripts` contains bash and Python scripts to check the individual components of the system test.


This can actually be deleted as I think it referred to test scripts that no longer exist

skeating added 4 commits November 27, 2024 15:55

update main read me

93dc6ba

update main read me (#529)

edbf6dc

Merge branch 'sk/joss-1' into sk/joss-pub

235ca58

Merge remote-tracking branch 'origin/sk/joss-publication' into sk/jos…

8d7faf6

…s-pub

skeating added 14 commits December 24, 2024 14:39

made read mes consistent

65c7b5f

Made the read mes more consistent

3dcc4fb

made read mes more consistent

a48ec93

making readmes consistent

7c777c9

making readmes consistent

4109db4

making readmes consistent

08b4ca5

making readmes consistent

474894e

Making readmes more consistent

b0360ea

Making readmes consistent

2babe4d

Merge remote-tracking branch 'origin/main' into sk/joss-pub

6bf6989

Making readmes consistent

415761f

Making readmes consistent

57f13b9

Making readmes consistent

e00eeae

Making readmes consistent

35c34b2

skeating requested a review from stefpiatek January 13, 2025 09:57

skeating marked this pull request as ready for review January 13, 2025 09:59

Merge remote-tracking branch 'origin/main' into sk/joss-pub

95be8f9

skeating requested a review from tomaroberts February 11, 2025 15:51

Merge branch 'main' into sk/joss-pub

9fee555

tomaroberts changed the base branch from sk/joss-publication to main March 4, 2025 10:23

tomaroberts changed the base branch from main to sk/joss-publication March 4, 2025 10:24

tomaroberts requested changes Mar 4, 2025

View reviewed changes

Apply suggestions from code review

89b0710

Co-authored-by: Tom Roberts <[email protected]>

Merge branch 'sk/joss-publication' into sk/joss-pub

2a15810

stefpiatek requested a review from tomaroberts July 7, 2025 08:34

stefpiatek reviewed Jul 7, 2025

View reviewed changes


		Save the credentials in `.secrets.env` and a LastPass `Hasher API <environment> secrets` note.

		SK QUESTION: is the reference to Last Pass something that is specific to us or is it a dependency somebody else would need. actually I assume the whole Azure thing is rather how we have chosen to do that rather than a necessity for somebody i.e. they might use a different system for storing their hashes

	Once the study and all its instances are in `orthanc-raw`, the study is sent to `orthanc-anon` via a C-STORE <SK: Please explain what C-STORE operation>
	Once the study and all its instances are in `orthanc-raw`, the study is sent to `orthanc-anon` via a [DICOM C-STORE operation](https://www.medicalconnections.co.uk/kb/Basic-DICOM-Operations).

		@@ -0,0 +1,10 @@
		## 'ISSUE_TEMPLATE' Directory Contents

		### Files

		@@ -0,0 +1,16 @@
		A directory that contains the files used for linting.

	A directory that contains the files used for linting.
	Custom linting

	[project configurations](../README.md#configure-a-new-project). <== SK comment I'm not sure this goes to exactly the right place OR the name in the # is misleading
	[project configurations](projects/configs/README.md)

	- Will throw a `PixlSkipInstanceError` for any series based on the project config file. {SK: this sentence doesn't quite make sense to me} Specifically, an error
	- Will throw a `PixlSkipInstanceError` for any series that should be skipped (based on the project config file). Specifically, an error

Adding READMEs to all directories #584

Are you sure you want to change the base?

Adding READMEs to all directories #584

Uh oh!

Conversation

skeating commented Dec 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Suggested Checklist

Uh oh!

codecov bot commented Dec 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

skeating commented Jan 13, 2025

Uh oh!

stefpiatek commented Jan 28, 2025

Uh oh!

tomaroberts left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

stefpiatek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

skeating commented Dec 24, 2024 •

edited

Loading

codecov bot commented Dec 24, 2024 •

edited

Loading