-
Notifications
You must be signed in to change notification settings - Fork 621
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
Separate reference docs from manual pages #4766
base: master
Are you sure you want to change the base?
Conversation
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
✅ 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 <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
After discussing with Paolo and the team, we are thinking more to organize the docs like the Docker Docs. The key implication for this PR is that there will not be one general "user guide" and "reference". Instead, there will be a "Guides" section which contains many guides targeted to specific use cases, such as a quickstart for each cloud provider, HPC schedulers, etc. The existing "reference" docs are more accurately described as a "manual" which also contains reference material. Instead of trying to factor out the user guide content, I will keep the docs as they are but just try to better separate the reference material from the "manual" pages. I will refactor this PR accordingly and continue to restructure the existing docs, but also carve out a space for the team to start writing the guides. These efforts can be pursued independently, but since they both depend on a new deployment framework, no harm in keeping them together for now. |
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Some notes on the Nextflow training and nf-core docs after a brief review:
Because I have pulled out the reference material (config scopes, channel factories, process directives, etc), the manual pages for config, channels, process, etc have a lot more breathing room to give some illustrative examples. As a result, I think the basic training can be condensed significantly by just linking to the docs more instead of duplicating it. Instead it can focus on walking through the writing and testing of a specific pipeline example. |
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
After discussing with Paolo, we would like to only keep the manual + reference docs in the Nextflow repo. Additional content like targeted guides and tutorials should be maintained somewhere else and can be combined with the reference docs at build time. To that end I have trimmed this PR to focus on the internal improvements to the existing docs. These changes can be merged independently of other efforts like writing guides, deployment framework, website overhaul, etc. |
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
This PR is ready for review. Going to do one more pass to iron our any rough edges. This PR has evolved in scope since it was created. To clarify, the purpose of this PR now is to reorganize some pages and sections to be more user friendly, and to make it easier to pull out higher-level content for the docs team in future iterations. |
Found some rough edges with the process docs, should have it resolved today |
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
@ewels @pditommaso shall we move this forward? Everything looks good to me, but as long as you agree with the basic structure, we can refine things in future (smaller) PRs. This one is getting difficult to maintain |
I'm not sure we should do this; we are continuing refactoring this doc, making links unstable. I assume new docs should go into docs.seqera.io, after that we can progressively reorganize this as needed. |
This restructure is a prerequisite for moving docs to seqera docs because it makes it easier to pull out the user guide content |
Let's solve the conflict and I'll give this another try |
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Ready 👍 |
Has something changed in the deps? I'm getting this while building the docs
|
Looks like the You know you can just use the deploy preview: https://deploy-preview-4766--nextflow-docs-staging.netlify.app/ |
it's running in the container make via Line 1 in e2f74b4
|
Think you need to add git to the container, it is being used by the docs build now: Lines 70 to 72 in ea8246f
|
Signed-off-by: Paolo Di Tommaso <paolo.ditommaso@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
@pditommaso this PR is up to date. Let's get it merged so that we don't have to keep fixing conflicts |
@bentsherman have a look at those conflicts please |
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
This PR reorganizes the docs in a number of ways:
The original exploration was around refactoring the docs into a user guide vs reference manual. After a few iterations, the main focus now is the first two items, separating the reference docs and reorganizing the sections to be more user friendly.