Skip to content

Break up compute example and make it publishable#8

Merged
sirosen merged 2 commits intoglobus:mainfrom
sirosen:publish-compute-doc-example
Apr 18, 2025
Merged

Break up compute example and make it publishable#8
sirosen merged 2 commits intoglobus:mainfrom
sirosen:publish-compute-doc-example

Conversation

@sirosen
Copy link
Member

@sirosen sirosen commented Apr 15, 2025

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).

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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...)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@sirosen sirosen merged commit 36b5afc into globus:main Apr 18, 2025
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants