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

RESOLVED FIXED

Status

Taskcluster
Documentation
--
enhancement
RESOLVED FIXED
4 years ago
2 years ago

People

(Reporter: jonasfj, Assigned: dustin, Mentored)

Tracking

(Depends on: 1 bug)

Details

(Whiteboard: [taskcluster-q32015-meeting])

Comment hidden (empty)
(Reporter)

Comment 1

4 years ago
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.
(Reporter)

Comment 2

4 years ago
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.
(Reporter)

Comment 3

4 years ago
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.
(Reporter)

Comment 4

3 years ago
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 :)
(Reporter)

Comment 5

3 years ago
the other related by I was mentioning is bug 1070756.
(Reporter)

Comment 6

3 years ago
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
(Reporter)

Updated

3 years ago
Depends on: 1091780
Component: TaskCluster → General
Product: Testing → Taskcluster
(Reporter)

Updated

3 years ago
Whiteboard: [taskcluster-q32015-meeting]
just a note that we might want to query the provisioner to possibly generate docs for worker types.
Component: General → Documentation
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.
Assignee: nobody → dustin
Let's move that last bit to bug 1257945
Status: NEW → RESOLVED
Last Resolved: 2 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.