-
Notifications
You must be signed in to change notification settings - Fork 638
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document formal script syntax #5336
Conversation
Signed-off-by: Ben Sherman <[email protected]>
✅ Deploy Preview for nextflow-docs-staging ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
I agree having everything on the same page would be too much, and I'm also not sure if that would make the most sense for someone accessing the docs. So I guess the question is where the bulk of the syntax should be described in detail (a single page or separate pages). I wonder if there can be a compromise where the bulk or common syntax is described on a Syntax page but also have Syntax sections (e.g., Groovy closures). The "main" syntax page could have small sections about the other syntax sections and then link out, rather than build everything into one page. |
I was thinking something similar, have a top-level page that links out to the existing pages. Two questions around that:
I think we could just repurpose the "Scripts" page with an outline like this:
Then add a "Syntax" reference page which is actually a full description of the script grammar. This way the "Scripts" page doesn't have to be comprehensive on basic syntax, it can just provide the most important examples. The reference page can get very specific on things like punctuation, what kind of code is allowed where, etc In any case, we need to have a broader conversation on how to evolve the docs from here, but I think for now I can do a first draft and let us iterate on that |
I was thinking something similar:
I think this would align nicely with splitting user and reference content too. |
Signed-off-by: Ben Sherman <[email protected]>
Please keep PR small |
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Adding a few comments for visibility now.
Okay I think I found a good scope for this PR:
Some items for future PRs:
Thanks @christopher-hakkaart for the comments, I will address them shortly |
Co-authored-by: Christopher Hakkaart <[email protected]> Signed-off-by: Ben Sherman <[email protected]>
Co-authored-by: Christopher Hakkaart <[email protected]> Signed-off-by: Ben Sherman <[email protected]>
Co-authored-by: Christopher Hakkaart <[email protected]> Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looking good. I've reviewed every md page - except the new syntax page.
I like the direction of the syntax page but I find some of the descriptions too short. E.g., comparing the comments section here and the groovy sytnax page. What do you think about adding more context to some of these? Do you think it would be too repetitive?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Had a quick run through of just the new syntax.md
file and dropped a few first impressions.
This is great!
Co-authored-by: Christopher Hakkaart <[email protected]> Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Christopher Hakkaart <[email protected]>
This reverts commit 597e06e. Signed-off-by: Christopher Hakkaart <[email protected]>
c9043f8
to
505c98e
Compare
Signed-off-by: Ben Sherman <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is looking awesome.
I've added some suggestions to turn passive into active voice and split some sentences. I don't see any of these as blockers but opportunities to improve clarity. If you're happy with these I think it's good to go.
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for adding my suggestions. The docs look good to me.
Signed-off-by: Ben Sherman <[email protected]>
This reverts commit 48ac8b5. Signed-off-by: Ben Sherman <[email protected]>
cee507a
to
30ea996
Compare
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Paolo Di Tommaso <[email protected]>
I've left out the mention to deprecation because deserver further discussion 👉 3f6f377 |
Signed-off-by: Ben Sherman <[email protected]> Signed-off-by: Christopher Hakkaart <[email protected]> Signed-off-by: Paolo Di Tommaso <[email protected]> Co-authored-by: Christopher Hakkaart <[email protected]> Co-authored-by: Paolo Di Tommaso <[email protected]>
Now that the docs are in better shape, we can begin work towards a formal description of the Nextflow language, as well as prepare the docs and tests for the strict syntax that will be introduced by #4613 and #4744 .
Refer to the changes to snippets and tests for examples of strict syntax:
it
closure parameter with explicit parameterenv
input/output nameCurrently the syntax description is split across several pages:
It would be nice to have a single page that describes the entire language. At the same time, I don't want to move these pages around much more, and they are too hefty individually to combine them.
Since these pages cover a lot of other topics like APIs and runtime behavior, maybe it would be better to add a new page e.g. "Reference > Syntax" which gives a top-down syntax description.
Looking to the Groovy docs as an example, I feel like the Scripts page could be expanded to also describe process/workflow/include syntax. It just feels weird to mention them here when there are already dedicated pages.