Break up compute example and make it publishable#8
Conversation
Break the readme up into chunks with github-specific rendering directives, then use the build script to concatenate those chunks and produce a monolithic example page for the docs site. In the process, fully review the example documentation, convert it to asciidoc, and make stylistic adjustments (most notably, bold terms to follow the docs.globus.org style guidance). Also switch many present-progressive phrasings to imperatives and remove excess descriptive text whenever possible. The doc build script itself (and the schema) gained support for arbitrary file inclusions from the example directory, in support of the structure which does not currently match other existing examples.
| link:https://docs.globus.org/globus-connect-server/v5.4/[this guide for setting up a Globus Connect Server Collection] | ||
| to install Globus Connect Server and configure a **collection**. | ||
| + | ||
| For ease of use, we recommend using a Guest Collection. |
There was a problem hiding this comment.
I'm not sure we want to recommend this, because even though this is a good general recommendation, it may actually be more complicated for them to get right given that it makes it harder to reason about the path transformation needed? (Admittedly, though, this is such an expert-user/admin feature that I'm still trying to figure out how worried to be about this...)
There was a problem hiding this comment.
It's not a clear win in all cases -- definitely a tradeoff. I'd be more gunshy about it if we weren't providing the flow.
The flow already contains the complexity around the base path manipulations. Given that the major cost of supporting Guest Collections in the flow has already been paid, I'm therefore pretty well inclined to stick with this as our guidance.
Co-authored-by: Ada <107940310+ada-globus@users.noreply.github.com>
Break the readme up into chunks with github-specific rendering directives, then use the build script to concatenate those chunks and produce a monolithic example page for the docs site.
In the process, fully review the example documentation, convert it to asciidoc, and make stylistic adjustments (most notably, bold terms to follow the docs.globus.org style guidance). Also switch many present-progressive phrasings to imperatives and remove excess descriptive text whenever possible.
The doc build script itself (and the schema) gained support for arbitrary file inclusions from the example directory, in support of the structure which does not currently match other existing examples.
This build was tested, integrated into the docs site build, and produces a single page as desired.
Optionally (upon request from a reviewer + discussion), we can revert the decision I've made to break up the readme into parts in the github case. I believe it leads to better presentation, but was not prepared to pursue a structure like this for docs.globus.org rendering (at least, as of yet).