Improve doc build system

[briandoconnor]

James E. gave some feedback that we can work on in a new PR:

.travis.yml @@ -35,6 +35,25 @@ jobs: # Travis will install requirements.txt by default - flake8 --select=E121,E123,E126,E226,E24,E704,W503,W504 --ignore=E501 app.py tests

 # the build process from James Eddy adapted from the WES repo

@jaeddy jaeddy on Dec 14, 2018 Member Just a note: the steps/stages described under jobs should be able to replace the python and stages sections above. Might be a task for a separate PR.

[briandoconnor]

gulpfile.js @@ -0,0 +1,50 @@ var gulp = require('gulp'); @jaeddy jaeddy on Dec 14, 2018 Member I'm about 95% sure that this file isn't needed anymore. It's leftover from when I was using a separate node job in Travis to build the Swagger UI.

[natanlao]

It looks like ga4gh.github.io/data-repository-service-schemas/swagger-ui/ etc. is broken

[jaeddy]

I've come across that before with the WES repo — pretty sure it's a bug in the logic of either the fetchpages.sh or stagepages.sh script (in particular, the if [ "$TRAVIS_BRANCH" <something> ] statements). I'll take a closer look and try to remind myself what's happening here...

[natanlao]

I think I see the bug and can probably push a PR within the next couple of days. In that vein, I'm thinking of tweaking the build framework such that:

• The code for Swagger UI (currently in web_deploy/swagger-ui/) is moved to _swagger-ui/
• web_deploy/swagger-ui/ is replaced with one file, web_deploy/swagger-ui/index.html, which is a frame that points to _swagger-ui/ and updates the child frame with the (calculated absolute) path to the correct schema
• On a build, only web_deploy/swagger-ui/index.html is copied

I've tested this locally, and it seems to work fine. It's not an imperative optimization, but the swagger-ui/ directory is 4.0M, and I think it could be worthwhile.

[jaeddy]

+1

Awesome — that sounds great, @natanlao!

Something else that could be useful when addressing this bug is adding some print/echo calls for Travis environment variables (e.g., "$TRAVIS_BRANCH", "$TRAVIS_PULL_REQUEST", "$TRAVIS_PULL_REQUEST_BRANCH") such that they're visible in the build logs. Maybe it's just me, but this currently feels a bit like a black box, which makes it harder to predict behavior.

[natanlao]

I think the only thing needed to close this ticket is to add some test to ensure that the build system is working as expected.

[briandoconnor]

Related to #230 . Stale issue, can we close?

[jb-adams]

Suggest closing this issue, as #359 updates the docs build process to use gh-openapi-docs

@briandoconnor @dglazer