singularityhub/singularityhub-docs

improved documentation for Singularity Hub

singularityhub-docs's Issues

Internal links on /builds/README.md don't work

The links under Building Options on https://singularityhub.github.io/singularityhub-docs/docs/builds don't work in production, as they miss the /builds/ part of the path. E.g., https://singularityhub.github.io/singularityhub-docs/docs/automated doesn't work, whereas the correct link (as in the TOC) https://singularityhub.github.io/singularityhub-docs/docs/builds/automated does.

Interestingly, this doesn't show in a local serve I've just done from master, where the link [Deployment Build](deployment) resolves correctly to http://127.0.0.1:4000/singularityhub-docs/docs/builds/deployment.

This is strange behaviour. Is the live version of the docs built from master?

[User Guide correction]Image building issue for the first Singularity file

Links

N/A

Version of Singularity

N/A

Behavior when Building Locally

N/A

Error on Singularity Hub

The Singularity file created before Add a new repository is not built.

What do you think is going on?

I am new to Singularity so I followed the Use Guide step by step to create my first image: Build A Contrainer

In the User Guide, it is recommended to create a first Singularity file before adding the repository to Singularity Hub: Steps

However, I noticed that by doing so, the predefined Singularity will not trigger a build in the Automated Build mode.

After reading the documentation of Automated Build, I notice that Singularity Hub will only check the commits after the connection being established. Thus, if we follow the steps described in the user guide, the very first Singularity is excluded, unless we modified this file later and commit again.

I suggest that in Steps, the connection should be established before committing the first Singularity file. (Verified and approved to be OK)

It is not a fatal issue but it would cause some trouble to understand what happened, especially for a newbie.

Resolve discrepancy in usage documentation

In the Image interaction section of the docs, it says that

You should never issue any of the following commands

singularity run shub://vsoch/hello-world
singularity shell shub://vsoch/hello-world
singularity exec shub://vsoch/hello-world ls /

However, if you look at the Usage page in the shub UI (btw, IMHO the titling suggests access to usage stats), it implicitly warns to not use containers directly from shub as each run is 1/100 downloads. It goes on, however, to only give that exact example in the "Run a container" section of the page.

I think it'd be good to separate the different concerns of the page a little better.

Concern 1) seems to be to present all options for interacting with shub from the CLI, so it does make sense to include the Run a container example with a run command using shub directly.

Concern 2) is "hidden" in the warning box on top, i.e., presenting the best practice of pulling first, then using the local version.

I'd suggest getting rid of the warning box and introducing a "best practice" section that includes the info from the box + gives a simple example along the lines of, e.g.,

# First, pull the container from Singularity Hub
singularity pull shub://sdruskat/getpapers-singularity

# Then interact with it
singularity run getpapers_singularity 
[NOTE I'm not actually sure what the container would be named, as I haven't built and pulled one yet, I guess getpapers_singularity_latest?)

What do you think?