User docs: FAQs

[ana-v-espinoza]

@julienchastang please add to this list if you notice something is missing or needs attention

New FAQs

• How to restart servers
• Gitpuller failed; what now?

Needs attentions

• Links on GitHub are broken
  • Trailing ?s break the URLs
  • Forward slashes / break the URLs
  • I think the links still work when viewing on JupyterLab's Markdown Viewer, may have to prioritize one or the other

[julienchastang]

Thanks. Have you tried URL-encoding?

[ana-v-espinoza]

That doesn't seem to have the effect we want.

From a JupyterHub terminal:
curl -L https://github.com/Unidata/science-gateway/blob/master/user-docs/admin-docs.md?raw=true --output ./admin-docs.md

Opening that in JupyterLab's Markdown viewer and clicking, for example, the How do I use my environment/kernel? link in the Table of Contents works fine. This takes me to:
https://<hub-url>/user/<user>/lab/tree/admin-docs.md#How-do-I-use-my-environment/kernel?

This works as expected.

Using URL encoding works as well, i.e.:
https://<hub-url>/user/<user>/lab/tree/admin-docs.md#How-do-I-use-my-environment%2Fkernel%3F

However, on GitHub, it seems the built in markdown viewer automatically sanitizes the links to the headers. For example:
https://github.com/Unidata/science-gateway/blob/master/user-docs/admin-docs.md#how-do-i-use-my-environmentkernel

Note the lack of / and ?. Thus, the encoded URL doesn't actually "go anywhere":
https://github.com/unidata/science-gateway/blobl/master/user-docs/admin-docs.md#How-do-I-use-my-environment%2Fkernel%3F

I could, as we do in other docs found on the repo, use an <a id=ID></a> tag and reference that in the link. This would make the link work on GitHub, however this feature is actually removed for the JupyterLab Markdown Viewer.

Perhaps some combination of the two could work...I'll check on that when I have time.

[julienchastang]

The root issue is a lack of a universal Markdown standard across platforms. I'd personally use the anchor IDs like we do everywhere else. If that does not work in JupyterLab, the user can just do text search. At any rate, I don't think it worth getting bogged down by. Done better than perfect.

[ana-v-espinoza]

Considering that the docs are more easily accessible to end users via the JupyterLab interface (it can be curled in to their home directories via the startup hooks), I'm partial to prioritizing that. In other words, "it works in JLab the way it is now; I'll touch it eventually to try and get the link working on GitHub too".

I'll save this task for a "slow" day.