Relationship between hosting-base-path and actual URLs is not very clear

[dabrahams]

Description

I'm having the most confounding time configuring docc, or understanding where to find the pages it generates. I've struggled with this in the past too, and got past it but somehow failed to internalize the answers. Maybe someone can help me (and hopefully, address this usability problem I seem to keep bumping into).
Here's a doc generation run. I expect to find the pages for the Core target at https://www.hylo-lang.org/hyloc/docc/Core/, similar to the pages generated by jazzy (this way) which are easy to find at https://www.hylo-lang.org/hyloc/jazzy/Core/. As you can see from the former URL, we get docc's custom 404 page but nothing interesting.
I recall somewhere docc was injecting /documentation/ into the paths somewhere, but I don't think I understand the rules.
In fact when I run the same commands locally, I get a site that refers to a theme-settings.json that doesn't seem to be anywhere in the directory tree.
Ugh, after digging around in my local filesystem, I find the results at https://www.hylo-lang.org/hyloc/docc/Core/documentation/core/. If I capitalize the 2nd "core" or lowercase the first one, it doesn't work. Maybe I'll just file this usability issue.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

No response

Actual behavior

No response

Steps To Reproduce

No response

Swift-DocC Version Information

No response

Swift Compiler Version Information

No response

[ethan-kusters]

Hi @dabrahams – thanks for filing this! Definitely work to do here.

Have you seen the DocC-Plugin docs on this? https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/publishing-to-github-pages#Publishing-the-Documentation-Site

I think that's the best we currently have – but agreed that there's more to do.

[dabrahams]

I have seen that. Very inadequate I'm afraid; it doesn't even show --hosting-base-path being used, and it gives the impression that docs is a magic name.

[ethan-kusters]

it doesn't even show --hosting-base-path being used

It does include instructions around --hosting-base-path – what sort of information were you hoping to see there?

it gives the impression that docs is a magic name

At least at the time the documentation was written /docs was a magic name. GitHub Pages supported emitting your documentation website into the root of your repository or into a directory named "docs" specifically. If that's no longer the case, we should definitely update the documentation to reflect that.

[dabrahams]

it doesn't even show --hosting-base-path being used

It does include instructions around --hosting-base-path

Not the section you linked to I'm afraid. There's something above that.

– what sort of information were you hoping to see there?

Whatever it takes to know how to set the option given that the directory in --output-path dir is hosted at some-particular-url.

I would be able to test this information by using the technique you described here with an appropriate URL.

it gives the impression that docs is a magic name

At least at the time the documentation was written /docs was a magic name. GitHub Pages supported emitting your documentation website into the root of your repository or into a directory named "docs" specifically. If that's no longer the case, we should definitely update the documentation to reflect that.

🤷 I am generating into a directory called _site. You can see the workflow here. I've forgotten the details of my pages config but the repositories owned by hylo-lang are under https://hylo-lang.org/name-of-repo, so instructions shouldn't assume otherwise.