1056282 - docs: Design for docs.taskcluster.net and general refactoring

Status: RESOLVED FIXED

(Taskcluster :: Services, enhancement)

Comment 1

[Jonas Finnemann Jensen (:jonasfj)]

Currently, docs.taskcluster.net has a quick a dirty design in bootstrap, and the whole thing is generated with jekyll.

This leads to a couple of horrible things:
 A) The menu is defined in the file (which is okay), but for every entry we define:
       - name:  (human readable name)
       - url:   (relative-url to file that contains this, example: /myfolder/index.html)
       - href:  (Url location to go to, example: /myfolder/)
    All this horror in order to make the menu show which page we are on, and make the the url in the
    browser be a nice: docs.taskcluster.net/queue/api-docs/
 B) We actually unroll the menu loop in two levels... this is aweful.. but necessary in jekyll.
 C) We should have menu entries at the top of the page, as this strictly limits the amount of top-level
    menu entries we can have. And reduces the ability to get an overview.
 D) All javascript things are included in most awful way possible, using <script> tags that are
    #ifdef'ed by the page variables...
    There must be a smarter (saner) way to do this (sorry I didn't care to learn it).
 E) All JSX files (for react.js) are built on-the-fly in the browser, this is slow...
    and makes debugging hard.

Getting some of these things cleaned up would be really nice.
The design doesn't have to be amazing, I'm perfectly happy with something that just smashes bootstrap together.
In fact we probably don't want to break with the current page size format...

Just make the menu one big side menu... Get rid of all the hacks required to use jekyl of github.
Move it something quick and easy to build and test with grunt.

Oh, and figure out how we can straighten out the client-side javascript situation. We can and will happily modify taskcluster-client, slugid, superagent-promise, listener.js from events.taskcluster.net to be easy to include in a sane way.
Perhaps bower, components or browserify is the solution to this. Ideally, we could define some package.json thingy and not have to update them manually either :)


So far many parts of the docs site is a hack... Building and uploading to S3 from travis would be nice.
If we use S3 instead of gh-pages it'll also be easy for us to add HTTPS using cloud front.
I have the required certificates, so contact me regarding that setup.

Comment 2

[Jonas Finnemann Jensen (:jonasfj)]

Oh, did I mention:
  F) In order to get nice urls like docs.taskcluster.net/queue/api-docs/
     we have a folder called api-docs/ and a file called index.html.
     Basically all of the HTML and markdown files are called index.html or index.md

Needless to say that all files being separate folder and being called index.(html|md) is very horrible.
And make it hard to find the right file when editing the documentation. We can do smarter than this.

Comment 3

[Jonas Finnemann Jensen (:jonasfj)]

When doing this we should probably consider moving all tools from the docs site into:
  tools.taskcluster.net

Note, looking at various things we used... some grunt setup is probably the way to go.

Comment 4

[Jonas Finnemann Jensen (:jonasfj)]

James and I had a discussion in another bug that it would be nice if docs were located in the repository they documented, and uploaded when we deployed the code. Like how references for apis and exchanges are done.

I wrote a proposal here:
https://etherpad.mozilla.org/jonasfj-taskcluster-documentation-rethink

We should discuss that...
I think making an API for references.taskcluster.net is near trivial, like half a days work.
Setting up S3 + cloudfront for SSL should be easy too (I have the certificates).
Only complicated thing is generating documentation from JSON files stored on references.taskcluster.net.
But that's already complicated :)

Comment 5

[Jonas Finnemann Jensen (:jonasfj)]

the other related by I was mentioning is bug 1070756.

Comment 6

[Jonas Finnemann Jensen (:jonasfj)]

Note, tools.taskcluster.net have been created and we have started to move tools to it. So hopefully we'll soon have removed all our tools from docs.taskcluster.net

Comment 7

[John Ford [:jhford] CET/CEST Berlin Time]

just a note that we might want to query the provisioner to possibly generate docs for worker types.

Comment 8

[Dustin J. Mitchell [:dustin] (he/him)]

I fixed most of the "horrible things" above.

I kinda hate Jekyll, but it is nice that Github generates and hosts the docs for us.  I don't think it'd be much harder to use a Node-based templating system that generates a site and use some command-line tool to upload that to an S3 bucket, then host the site on S3.  That would get us a bit more flexibility and remove the Ruby requirement.  But maybe not today.

The one thing I'd like to do here is to move the directories in the repo around to better match the menu structure.

Comment 9

[Dustin J. Mitchell [:dustin] (he/him)]

Let's move that last bit to bug 1257945