Skip to content

Split standard library docs into multiple pages #5993

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

Draft
wants to merge 7 commits into
base: master
Choose a base branch
from

Conversation

bentsherman
Copy link
Member

@christopher-hakkaart I tried splitting up the stdlib page into multiple sections. Moving each type to its own page isn't feasible right now because it creates too many levels of headings. So instead I just split at the level of constants/functions/types, which reduces the max length by a little bit.

To go all the way, I think we would need to split the "Reference" section into multiple sections:

Language

  • syntax
  • stdlib
  • feature flags
  • processes
  • channel factories
  • operators

???

  • CLI
  • config options
  • environment vars

I'm not sure what to call the second section but they seem loosely related. Configuration? User interface? There is also the concept of a "Runtime API" (e.g. the APIs used by plugins) that will need to fit in here one day, somehow.

Anyway, if we can find a sensible hierarchy here, maybe we can move this forward

Copy link

netlify bot commented Apr 21, 2025

Deploy Preview for nextflow-docs-staging ready!

Name Link
🔨 Latest commit d8c3e66
🔍 Latest deploy log https://app.netlify.com/sites/nextflow-docs-staging/deploys/6808325da24b6000086a0309
😎 Deploy Preview https://deploy-preview-5993--nextflow-docs-staging.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@christopher-hakkaart
Copy link
Collaborator

Love the direction. I'll do some research and thinking and try to come up with some options as well.

@christopher-hakkaart
Copy link
Collaborator

A few thoughts:

  • I really like splitting the pages out. I think we should be doing more of this across the nextflow docs to keep pages at a reasonable size.
  • The stlib page feels like an index or landing page for stdlib constants, functions, and types. I like this in principle, but I find that having the Groovy and Java classes below detracts from these links and makes them easy to miss. I'd propose making a page for Groovy and Java classes, adding a line of text, and then having a separate bullet point just for this. The page is short, but the text could be expanded to explain each category/page and then list the pages.
  • Some loose naming for the sections described above could be Language reference and Runtime reference. I'm still simmering on other options. I'm always a little conflicted about moving stuff around too much, one side, it's good to test and work out if it improves navigation, the flip side is confusing users who can't find moved content.
  • This could be expanded to other pages, process reference is an easy win.
  • Eventually, I could see pages like the stlib across the nextflow docs and using cards with descriptions to help direct users to the right content. See Docker docs and MultiQC as examples.

I got a bit excited and pushed my proposal to your branch. I've reverted, but you'll be able to see what I was proposing in the commits.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants