Following the build steps for contributing doesn't result in viewable example documentation

[lazarljubenovic]

Not sure if I'm missing something here, but after cloning and installing rush (first time I hear about it, so could be I'm missing something that should've been obvious) and running rush build, I'm getting the example/docs folder with certainly something, but after opening the browser I get a bunch of 404s and missing MIME types.

live-server's output is also complaining:

[ShukantPal]

I'm really coming off as a bad maintainer 🤦. Okay, so the GitHub pages URL has a /example-documentation path - but locally, we have/docs (if you start live-server in /examples).

So locally, you have to change the --site-root option to --site-root docs. A better solution would be to detect whether it's a CI environment and choose the site-root accordingly.

[ShukantPal]

This is required because I added a feature to make cleaner URLs, instead of outputting all the pages in a top-level directory.

So notice the URL https://webdoc-labs.github.io/example-documentation/@webdoc/example/PIXI/AbstractRenderer.html has directories - because of that webdoc needs the absolute URL to resolve links (and hence the site-root).

Templates can choose whether to use this feature or not - but @webdoc/default-template always uses it (open to adding it in config options).

---

JSDoc, and the "relative URL" mode would output something like:

https://webdoc-labs.github.io/example-documentation/PIXI_AbstractRenderer.html

which I found to be undesirable for organization.

[lazarljubenovic]

Haha, don't worry. I'm just trying to document all issues here so we can fix them later 😄 Yeah, nesting with folders certainly looks, both from the server side and the URL side.

Alright, got it to work by running yarn webdoc --site-root docs while in webdoc/example folder, and then simply running live-server (not live-server docs, I still get 404s with that). I tend to use python3 -m http.server for quick testing, and that works too (the docs are on localhost:8000/docs).

Not sure about how to add the extra step in the docs; should we add a script build-local which has the correct site-root and then hook that somehow with rush build?

[ShukantPal]

@lazarljubenovic We would probably look for an environment variable on the CI and then choose the site-root accordingly. If Azure doesn't have a built-in env var, we can create one in the CI script - https://github.com/webdoc-labs/webdoc/blob/master/azure-pipelines.yml

[ShukantPal]

Duplicate of #175