Flexibly configure base url

[rossbar]

An important component of review workflows is documentation site previews. A common pattern that we have relied on is uploading static builds as artifacts on pr opening/pushes. We were attempting to port this pattern to a mystmd-based workflow for tutorials and ran into a minor issue.

The CI provider (circleci in this case) injects workflow ID metadata in the URL where the artifacts are located. This results in HTML not rendering properly, presumably because the baseurl paths for the artifact preview are different than expected.

Proposal

I'm not sure what the best/easiest solution is here, but it'd be nice to work out a workflow to allow hosting properly-rendered html for PR review (having a solution that doesn't involve netlify would be a plus!). I fully recognize that the pattern described above may be an anti-pattern especially for the new mystmd workflow! Any/all ideas welcome! Pinging @Carreau as well.

[rowanc1]

Thanks @rossbar, appreciate the issue. There is a BASE_URL environment variable that can be set ahead of time. Do you know the build ID on circleCI?

For an immediate work around:

# For a URL like:
# https://output.circle-artifacts.com/output/job/aafb5283-2b71-4151-b842-dc790384eac3/artifacts/0/_build/html/index.html
export BASE_URL="/output/job/aafb5283-2b71-4151-b842-dc790384eac3/artifacts/0/_build/html"
myst build --html

You can likely drop the trailing /_build/html part and only upload that folder to CircleCI. Some docs at the bottom of this page on that variable (happy also for a PR to bring this up a level and make it clearer!):
https://mystmd.org/guide/deployment-github-pages

The theme framework that we are using makes some assumptions (at least in the default case) that the URLs are the same as how they were built, primarily on the location of the JS and CSS artifacts.

[Carreau]

Thanks that is great !

If we dont' know the ID (which it seem we do as you pointed in the PR), I belive we use the same than conda is using for some packages: use a long unique string (AS base URL) and then you can "just" search and replace it if you want to relocate the build.

[rowanc1]

It looks like the PR update worked!

https://output.circle-artifacts.com/output/job/2f17c17e-a680-4e5c-a008-5460b25130ac/artifacts/0/_build/html/index.html

There are some issues with the .html not auto resolving to the HTML page. This is something that we can potentially address in the theme as well, but there may be configuration for CircleCI to auto-resolve these. There is an issue here that says they would open an issue, not sure if that resulted in some configuration to turn on?

https://discuss.circleci.com/t/circle-artifacts-com-not-using-index-html/320

Related:

• Rewrite internal links to include .html for static html (based on config) #950

[rowanc1]

I am going to close this as I believe this particular issue is unblocked - there is still the remain issue #950 that needs to be fixed up for static build serves that don't redirect to HTML natively.

Let me know if you need any other help with myst-ifying numpy tutorials. 🚀