review pydicom docs and integrate here!

[massich]

Are you familiar with Jekyll?

Some

I would suggest to start is go from the old docs base and first add the three missing pages (there were three more pages, "transition_to_pydicom.rst", "viewing_images.rst" and "working_with_pixel_data.rst" that we would want to add (and link to on the appropriate places) to be caught up with where the old docs were. >What I was doing is like:

• make a new page in pages/docs/pydicom by copy pasting another file
• copy the old content into the file, convert rst into markdown syntax
• preview, fix old links, tweak as needed
• add link to any pages that reference it, and/or sidebar

This is great, and we can start by this. But shouldn't be be improving the package documentation and then let sphinx and cricle ci build the website as in sci-kit learn?

any kind of new tutorial / other that you want to add would be awesome!

I would definitely add one on how to use DCM and RTSS to load volumes and overlay ground truth.

[vsoch]

Hey @massich ! I really like sphinx too, but I've found it to be a harder learning curve using rst syntax than simple markdown. A jekyll site is harder to setup the base for, but once it's there, it's super easy for the layerperson or new user to add content! Jekyll renders automatically (meaning builds) on github pages, so there is huge advantage to that (eg, what you push to master renders live!) If we want preview for PRs I can definitely add that to circle!

[massich]

The problem of jekyll is that you need to maintain the documentation in two different places.

[vsoch]

I'm ok if you want to maintain docs with the pydicom code base - the pydicom.github.io can have a high level intro and then link there for more details. It's mostly important to have one cohesive entry point for finding all these things.

[massich]

I agree that we should have a common place to introduce the community, the projects and testing data to get started. There's no problem in using Jeckyll for this introduction page.

However, I would keep the documentation related to each package within the package codebase (and using sphinx ... I will come back later on that). IMHO separating the examples from the codebase has two main problems: (1) they are harder to maintain, and (2) spreads the information which ends up confusing the user.

The documentation of pydicom (the software) could be improved. We could build a set of examples (using sphinx-gallery) and a more broader user guide, similarly to what we are using in our different projects in scikit-learn, nilearn, or imbalanced-learn. I am almost sure that similar thing can be drawn for the other packages which will be part of the pydicom community.

Acting in this regard, contributors will be able to focus on the project which they have more affinity with, which will be beneficial with more curated code and documentation. The pydicom organization will allow to bring all those together without duplicating efforts.

WDYT?

[vsoch]

That sounds like a great idea! If we can have assurance that it will be relatively easy for any user to PR, or any admin to update docs, then I'm ambivalent to where they are. I would, however, advocate for a design that, even if it's not exact, at least sort of matches to give unity to the overall look. I'll hold off adding any more to this repo for pydicom as you update the sphinx docs, and then what we can do is have a main page for each code base on the pydicom.github.io site that links to their main docs.

[vsoch]

My preference has migrated from sphinx to jekyll over the years because it removed an entire step of needing to host the sphinx docs somewhere, or if not using readthedocs, have some CI build and then deploy. And then there are sometimes bugs with the builds on readthedocs. I like jekyll because:

• markdown is much easier to learn / understand than rst. Making links and general formatting with rst just isn't as intuitive or easy for the new user
• jekyll will deploy locally with jekyll serve, and updates go live. You don't have to build and then start a server to preview as you do with sphinx
• jekyll will also be built automatically by github. I make a change, push, and my site is updated. The middleman of continuous integration / readthedocs is removed.

[vsoch]

It's important to make the steps of contributing content, whether that is code or docs, as transparent and easy as possible. I can see a user being comfortable with copy pasting a markdown file and then adding it, versus having a harder time understanding how rst / sphinx works.