FileSet and DICOMDIR usage documentation

[kwsp]

As a new pydicom user trying to read the Patient->Study->Series hierarchy from a DICOMDIR file, my internet search let me to this tutorial https://pydicom.github.io/pydicom/stable/tutorials/filesets.html . From this and some other pages I found, I got the impression that pydicom is really pushing for the flattened file structure provided by FileSet. However, it was very unintuitive to try to parse the data into Series until an hour later I came across this tutorial https://pydicom.github.io/pydicom/stable/auto_examples/input_output/plot_read_fileset.html#sphx-glr-auto-examples-input-output-plot-read-fileset-py

Proposed Change

1. [DOC] Link the tutorial for navigating the hierarchy in the FileSets tutorial (Trivial)

When I search some variations of "DICOMDIR FileSet iterate Series", the FileSets tutorial has much better SEO and always appears first (tested Duckduckgo and Google. However, nothing in this tutorial sheds light to new users who are used to the "Patient->Study->Series" hierarchy on how to actually navigate between Series. I propose we link this example, which actually shows how to parse and read Series from the DICOMDIR file. As I mentioned before, somehow this example is very hard to come by from the search engines, and Sphinx search is impossibly slow.

2. [FEATURE] Add an API to FileSet for iterating over Patients, Studies, and Series.

FileSet pushes the flat hierarchy, but for me personally its much easier to navigate a large DICOMDIR data directory through the hierarchy. As far as I'm aware this requires a lot of boilerplate code that could easily be abstracted away into an iterator API. I'm happy to work on this if the maintainers approve.

The reason I grouped these two "separate" issues together is that if proposal 2 is implemented, we'll just add new documentation for the new API instead of linking to the old example.

[scaramallion]

I didn't really push for a flat structure, it's just mostly how it worked out. I tend to usually use find over the whole fileset for the particular patient/series I need so I never saw the need to use the hierarchy. But I think it'd be great if you want to add an easy way to do so.

[mrbean-bremen]

and Sphinx search is impossibly slow.

Yes, I've noticed this a couple of times - it is practically impossible to use. I thought that this was due to some browser plugin on my side, but that is not true. I wonder if we are doing something wrong here and there is a way to speed this up. This would avoid to fallback to Google search, which is not optimal, and greatly improve the usefulness of the pydicom documentation.

[kwsp]

@scaramallion I see. I've been trying find as shown in the examples but it somehow doesn't satisfy my needs yet. I play around a bit more and see what's the optimal workflow for me and I'll get back here.

[kwsp]

@mrbean-bremen I recall search not working in a lot of documentation sites built by sphinx. I'm debugging this issue

[kwsp]

@mrbean-bremen Found the issue. #1965