Add the ability to use regexps for snippet delimiters

[johndgiese]

Our command rdm collect grabs snippets from various files. Sometimes, e.g. in markdown files, it would be nice if the delimeters had the form

<!-- RDOC snippet_id -->
Snippet stuff goes here
<!-- ENDRDOC -->

This lets us delimit snippets without adding garbage to our markdown files.

Perhaps we can replace start_token with start_regex, where the regex has a capturing group for the snippet id. Thus, the HTML comment feature could use:

start_regex = '<!-- RDOC (.*) -->'
stop_regex = '<!-- ENDRDOC -->'

(or something similar).

It would also be nice to be able to grab snippets from python docstrings. E.g.:

class MyClass:
    '''RDOC my_class
    '''
    # stuff goes here

Or, even more ideal, it would be nice if we could grab the python class snippets without needing RDOC at all!

[johndgiese]

@orwonthe once the other outstanding issues are done, it may be worth spending some time thinking about this issue. Also, I wonder if we can learn anything from Sphinx or other code documentation tools.... I have also wondered if rst would have been a better format than md files?

[johndgiese]

E.g., I think restructured text supports a number of things we are building extensions on markdown for...

[SimonBiggs]

E.g., I think restructured text supports a number of things we are building extensions on markdown for...

Actually, there is an awesome middle ground between markdown and restructured text built by the Jupyter Book team:

https://jupyterbook.org/content/myst.html?highlight=myst

It is managing to keep the simplicity of markdown while bringing in what they need from "restructured text" land. It's quite awesome!

[johndgiese]

@SimonBiggs thanks a lot for sharing this link! I hadn't heard of myst. It does seem very nice. I like that their directives will show up as code snippets in editors that don't support the syntax.

[SimonBiggs]

I like that their directives will show up as code snippets in editors that don't support the syntax.

Yeah. I've been really liking JupyterBook (the team who created myst), they've put a lot of thought into it. I've been using it to build the PyMedPhys docs:

https://docs.pymedphys.com/

Under the hood it is still using sphinx, but, you don't need to know that they are.

Here's their docs website source code:

https://github.com/executablebooks/jupyter-book/tree/master/docs

It's essentially yaml and markdown (myst).

Their configuration approach is quite nice and powerful:

https://github.com/executablebooks/jupyter-book/blob/master/docs/_config.yml

Here's the rendering of their docs:

https://jupyterbook.org/intro.html

---

Also, as an aside, I have been thinking about doing all of my regulatory work out in the open:

https://github.com/RadiotherapyAI/regulatory

What are your thoughts about that? Am I crazy?

[johndgiese]

Thank you for sharing all of these links. I don't think it's crazy to do your regulatory work out in the open. We've considered doing an 510(k) for a small project in the open to provide an example of using RDM to our clients.

[SimonBiggs]

I don't think it's crazy to do your regulatory work out in the open

Thanks David :),

We've considered doing an 510(k) for a small project in the open to provide an example of using RDM to our clients.

That's awesome, and sorely needed. We've seen that need here in Australia with our regulatory body's new SaMD legislation. As a result as a Medical Physics college in Australia we have been thinking of making a very small completely open source project that uses RDM as a demo.

We were thinking of making a treatment planning script that checks a couple of low hanging fruit checks that TG275 highlighted as should be automated in radiotherapy.

The goal is to make the usage of RDM accessible to medical physicists writing in-house software.

We have been meeting weekly at 8:30 am Thursday NSW Aus time (which is 4:30 pm Wednesday New York time) to get this demo repository rolling. It is a collaboration between Medical Physicists at multiple hospitals around Australia. Is this a meeting you, or someone from Innolitics, might be interested in coming along to?

---

With my own company's software (Radiotherapy AI) the code itself would still be closed source, and as such if I want to have my regulation work be put in the open then it would need to be in a separate repo. Any recommendations/foreseeable pot holes around using RDM with the code repo and the regulatory repo being separated?

My experience with RDM is still quite small. I suspect there may be a few difficulties around linking commits to issues... But maybe I could overcome that with some submodule trickery or something equivalent. Anyway, I'll still be giving the open repo concept more thought, potentially may not even end up going down that path...

If it is open regulation, it would be quite cool if the whole set of regulatory documents were able to render like a JupyterBook online for any lay-person to read. If I do decide to go down this route, might you be open to having me create a flag within RDM that allows the backend to change to utilising JupyterBook? That way, I can begin extending RDM with JupyterBook functionality behind an opt-in flag which means other's usage of RDM isn't broken, but I can still push my changes upstream into https://github.com/innolitics/rdm.

What are your thoughts?

...If I do go down that route, it won't be for at least another couple of months though.

[johndgiese]

@SimonBiggs I'd be interested in helping with the project. Unfortunately, Wednesdays at 4:30 pm EST is when we have our company wide meeting, which would be difficult to move. So that time slot will usually not work for me. What would you want my role to be on the project?

Any recommendations/foreseeable pot holes around using RDM with the code repo and the regulatory repo being separated?

I think a you could get around all of this using submodules without too much difficulty.

If I do decide to go down this route, might you be open to having me create a flag within RDM that allows the backend to change to utilising JupyterBook?

I suspect you could just modify the makefile in order to do this, without needing to make any changes to rdm. I'd need to know more details to say for sure.

[SimonBiggs]

So that time slot will usually not work for me.

What if instead the time was instead Wednesday's at 4 pm? You could be free to come in the first 15 - 30 mins as desired?

What would you want my role to be on the project?

Insight and guidance on the best way to use RDM within the demo project with the goal to have a completely open-source Apache-2.0 repository that acts as a useful example of how to meet regulatory requirements utilising RDM.

I would expect you could attend for just a short portion of the meeting and we would give you an overview of what we've been doing and you would have the opportunity to inject any guidance or advice you might have around how best to demonstrate/use RDM to make sure that what we produce will be as useful as it can be for both your clients and Australian Medical Physicists.

Keen for your thoughts.

[johndgiese]

@SimonBiggs unfortunately 4 also wouldn't work, our company meeting is from 3:30 pm - 6:00 pm every Wednesday.

I'd be happy to help you guys as best I can. That said, before I get too involved, I'd like to see you make some progress defining what you're trying to accomplish and just proving that the group is serious. As best I can tell from the GitHub repo you mentioned, it seems like you're just getting started. I hope you can understand; I've seen a few projects like this come and go after having invested significant time on calls like this.

If you could write out a list of specific questions you'd like me to answer and send them to me, I can review them and schedule a time to talk through them with the group.

[SimonBiggs]

Yup, good call. Let us get to a point where we are really hitting some issues and we can best utilise your time.

On Thu, 9 Dec 2021, 3:36 am David Giese, @.***> wrote:

@SimonBiggs https://github.com/SimonBiggs unfortunately 4 also wouldn't work, our company meeting is from 3:30 pm - 6:00 pm every Wednesday.

Before I get too involved, I'd like to see you make some progress defining what you're trying to accomplish and just proving that the group is serious. As best I can tell from the GitHub repo you mentioned, it seems like you're just getting started.

If you could write out a list of specific questions you'd like me to answer and send them to me, I can review them and schedule a time to talk through them with the group.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/innolitics/rdm/issues/8#issuecomment-988976442, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABSBK67UP5IT2KUZJD5UVIDUP6CQ7ANCNFSM4F2RI5LQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.